agent.yaml şema başvurusu

Important

Bu makalede önizleme olarak işaretlenmiş öğeler şu anda önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve Microsoft üretim iş yükleri için bunu önermez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Uyarı

Aracı bildirimleri (agent.manifest.yaml) ve tek başına aracı tanımları (agent.yaml) kullanım dışıdır. Foundry azd uzantıları (azure.ai.agents 1.0.0-beta.1) itibarıyla, barındırılan tüm aracı yapılandırması tek azure.yamlbir içinde bulunur. Bkz . Barındırılan aracılar için azure.yaml ve barındırılan aracılar için azure.yaml başvurusu yazma.

AgentSchema belirtimi, yapay zeka aracılarını tanımlamak için açık bir standarttır. Barındırılan aracılar oluştururken öncelikle üç üst düzey şema türüyle çalışırsınız: AgentDefinition, AgentManifest ve ContainerAgent. , , AgentManifestAgentDefinitionve agent.manifest.yaml için agent.yamlbu eski şema modeli başvuru için tutulur ve yerine azure.yamltarafından alınır. Şema tek bir araç için özel değildir. Azure Geliştirici CLI'sı (azd) ve Visual Studio Code için Microsoft Foundry Toolkit bunu kullanır.

Şema, farklı adlandırma kurallarına sahip iki dosya bağlamında görünür:

agent.manifest.yaml , eski örnekler tarafından kullanılan parametreli bir şablon olan AgentManifest'tir. Geçerli azd ai agent init -t başlatma bir azure.yaml proje belgesi gerektirir ve AgentManifest sarmalayıcılarını reddeder.
agent.yaml, eski başlatmanın adresinde src/<agent>/agent.yamlprojenize yazdığı somut yapılandırma olan bir AgentDefinition'dır.

Her iki dosya da aracının ne olduğunu açıklar: modeli, araçları, protokolleri, ortamı ve kaynakları. Bu, Azure kaynaklarının azure.yaml sağlanıp dağıtılacağı hakkında bilgi veren 'den farklıdır. Başvuru için bkz. barındırılan azure.yamlaracılar için azure.yaml başvurusu.

Şema türleri

AgentDefinition

AgentDefinition, çalıştırmaya hazır bir aracının somut bir belirtimidir. Belirli bir yapılandırmaya sahip ve şablon yer tutucusu olmayan {{ parameter }} tek bir aracı örneğini açıklar.

Her AgentDefinition aracı türünü belirleyen bir kind alana sahiptir.

Kind	Description
`prompt`	Yalnızca yönergeler aracılığıyla yapılandırılan istem tabanlı bir aracı.
`hosted`	Kapsayıcı görüntüsü olarak dağıtılan kapsayıcılı aracı.
`workflow`	Diğer aracıları koordine eden bir düzenleme aracısı.

Oluşturulan AgentDefinition yine de başvurular içerebilir ${VAR_NAME} . Bunlar, AgentSchema belirtiminin parçası değil ortam değişkeni yer tutucularıdır azd . Dağıtım zamanında her ortamın dosyasındaki değerleri çözümleyerek tek bir tanım dosyasının birden çok azd ortamda .azure/<env>/.env çalışmasına izin verir.

AgentManifest

AgentManifest, aracıları dinamik olarak oluşturmaya yönelik parametreli bir şablondur. Bir AgentDefinition'ı alanı olarak template sarmalar ve ekler:

parameters: değiştirme söz dizimi kullanılarak {{ parameter }} oluşturma zamanında istemde bulunulur veya eklenir.
resources: model dağıtımları, araç kutuları veya bağlantılar gibi dış bağımlılıklar.

Yeniden kullanılabilir şablonlara ihtiyacınız olduğunda veya farklı yapılandırmalara sahip benzer aracılar dağıtmak istediğinizde AgentManifest kullanın. komutunu çalıştırdığınızda azd ai agent init, genellikle bir şablon seçerek veya URL sağlayarak bir bildirimi işaret edersiniz. Init işlemi parametre değerlerini ister ve bir AgentDefinition oluşturur.

ContainerAgent

ContainerAgent, ile kind: hostedbir AgentDefinition'dır. Kapsayıcıya özgü alanlarla temel tanımı genişletir ve barındırılan template bir aracı oluşturduğunuzda bir AgentManifest'in içindedir.

Bildirim veya tanım ne zaman kullanılır?

Şu durumlarda bildirim kullanma:	Şu durumlarda bir tanım kullanın:
Başkalarının örnek oluşturması için yeniden kullanılabilir bir aracı şablonu yayımlarsınız.	Belirli, tek amaçlı bir aracı dağıtırsınız.
Kullanıcıların modeli, araçları veya bağlantıları başlangıçta yapılandırmalarını istiyorsunuz.	Tüm yapılandırma değerleri bilinir ve sabittir.
Örnek veya başlangıç şablonu oluşturursunuz.	Zaten çalıştırdıysanız `azd ai agent init` ve bir tanımınız var.

Çoğu geliştirici bir bildirimden başlayıp azd ai agent init oluşturulan tanım ile çalışır. Şablon yazarları ve örnek yayımcılar, bildirimlerin birincil oluşturucularıdır.

Üst düzey alanlar

Aşağıdaki başvuru, tanım alanlarının üst kümesi olan bildirim alanlarını belgelemektedir.

Field	Türü	Zorunlu	Description
`name`	string	Yes	Aracı bildiriminin adı.
`description`	string	Hayır	Temsilcinin açıklaması.
`metadata`	object	Hayır	gibi `tags`ek meta veriler.
`template`	ContainerAgent	Yes	Aracı tanımı şablonu.
`parameters`	object	Hayır	Başlatma sırasında istenen yapılandırılabilir parametreler.
`resources`	Dizi	Yes	Aracının gerektirdiği kaynaklar.

template (ContainerAgent)

alanı barındırılan template kapsayıcı aracısını tanımlar.

Field	Türü	Zorunlu	Description
`name`	string	Yes	Ajan adı.
`kind`	string	Yes	Barındırılan aracılar için olmalıdır `hosted` .
`protocols`	Dizi	Yes	Protokol desteği.
`environment_variables`	Dizi	Hayır	Kapsayıcı için ortam değişkenleri.
`resources`	object	Hayır	Kapsayıcı CPU ve bellek kaynakları.
`image`	string	Hayır	Önceden oluşturulmuş kapsayıcı görüntüsü yolu.
`dockerfilePath`	string	Hayır	Dockerfile yolu.

Protokol

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0

Protocol	Description
`responses`	OpenAI Yanıtları API'si. Konuşma geçmişi yönetimini içerir.
`invocations`	Özel yük protokolü. Yerleşik konuşma yönetimi yok.

Tam protokol belirtimi için bkz . Barındırılan aracı çalışma zamanı sözleşmesi.

environment_variables

environment_variables:
  - name: FOUNDRY_MODEL_NAME
    value: ${FOUNDRY_MODEL_NAME}

Söz ${ } dizimi, ortamındaki azd.azure/<env>/.envortam değişkenlerine başvurur.

Uyarı

içinde FOUNDRY_PROJECT_ENDPOINTbildirmeyinenvironment_variables. Platform, bunu barındırılan kapsayıcılara otomatik olarak ekler ve azd ai agent run yerel geliştirme için ayarlar. Burada bildirimde bulunurken gereksizdir ve platform değerini gölgeleme riski vardır.

parameters

parametresi sırasında azd ai agent initparametreler istenir. Hassas değerler için kullanın secret: true .

parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token

resources

Kaynaklar, aracının neye ihtiyaç duyduğunu tanımlar. Aşağıdaki şekiller hangi bildirimlerin bildirdiği ve projenize nelerin azd ai agent init yazıldığı açıklanmaktadır. Başlatmadan sonra, doğrudan CLI komutları ile çalışma zamanında aynı proje kapsamlı kaynakları yönetin: azd ai connection, azd ai toolbox, azd ai skillve azd ai routine.

Uyarı

Şemada beceri alanı yoktur. azd ai agent init, azd ai agent runve azd up komutları becerileri otomatik olarak indirmez. Ile proje düzeyinde kaynaklar azd ai skill olarak becerileri yönetin ve bunları aracı çalışma zamanınıza kendiniz aktarın.

Model kaynağı

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

Bağlantı kaynağı

resources:
  - kind: connection
    name: MyConnection
    target: https://api.example.com
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ my_api_key }}"

Araç kutusu kaynağı

resources:
  - kind: toolbox
    name: agent-tools
    description: Agent toolbox
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: codeInterpreter
        type: builtin
        capability: code-interpreter
      - name: myMcp
        type: connection
        connection: "{{ MyConnection }}"

Araç kutusu sürümü üç tür girdi taşır: ham tools girişler (veya web-searchgibi code-interpreter yerleşik özellikler), connections (uzak araç MCP sunucusu veya arama dizini gibi proje bağlantıları) ve skills (mevcut proje becerilerine başvurular). Yuva tools bildirimde ön olarak bildirilir. ve azd ai toolbox connection addile azd ai toolbox skill add artımlı olarak bağlantılar ve beceri başvuruları ekleyin.

Tam örnek

name: my-web-search-agent
description: An agent with web search and MCP tools

metadata:
  tags:
    - AI Agent Hosting

template:
  name: my-web-search-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 2.0.0
  environment_variables:
    - name: FOUNDRY_MODEL_NAME
      value: ${FOUNDRY_MODEL_NAME}
    - name: TOOLBOX_ENDPOINT
      value: ${TOOLBOX_ENDPOINT}

parameters:
  github_pat:
    secret: true
    description: GitHub PAT for MCP connection

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

  - kind: connection
    name: GithubMcpConnection
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: github
        type: connection
        connection: "{{ GithubMcpConnection }}"

Değişken değiştirme

Değişim iki katmanda gerçekleşir: bildirim parametreleri başlatma zamanında, ortam değişkenleri ise çalışma veya dağıtım zamanında çözümlensin. Bundan sonra bir tanım dosyası tüm ortamlarınızda azd çalışabilir.

Sözdizimi	Çözümlenme zaman	Neye göre
`{{ param_name }}`	`azd ai agent init`	Kullanıcıdan gelen bildirim parametresi değerleri.
`${VAR_NAME}`	`azd deploy` veya `azd ai agent run`	`azd` ortamından `.azure/<env>/.env`ortam değişkenleri.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-07-07

agent.yaml şema başvurusu

Şema türleri

AgentDefinition

AgentManifest

ContainerAgent

Bildirim veya tanım ne zaman kullanılır?

Üst düzey alanlar

template (ContainerAgent)

Protokol

environment_variables

parameters

resources

Model kaynağı

Bağlantı kaynağı

Araç kutusu kaynağı

Tam örnek

Değişken değiştirme

İlgili içerik

Geri Bildirim

Ek kaynaklar