referensi skema agent.yaml

Important

Item yang ditandai pratinjau dalam artikel ini saat ini dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan Microsoft tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Note

Manifes agen (agent.manifest.yaml) dan definisi agen mandiri (agent.yaml) tidak digunakan lagi. Pada ekstensi Foundry azd (azure.ai.agents 1.0.0-beta.1), semua konfigurasi agen yang dihosting berada dalam satu azure.yaml. Lihat Penulis azure.yaml untuk agen yang dihosting dan referensi azure.yaml untuk agen yang dihosting.

Spesifikasi AgentSchema adalah standar terbuka untuk menentukan agen AI. Saat Anda membangun agen yang dihosting, Anda terutama bekerja dengan tiga jenis skema tingkat atas: AgentDefinition, AgentManifest, dan ContainerAgent. Model skema warisan ini untuk AgentManifest, AgentDefinition, agent.manifest.yaml, dan agent.yaml dipertahankan untuk referensi dan digantikan oleh azure.yaml. Skema tidak spesifik untuk satu alat. Azure Developer CLI (azd) dan Microsoft Foundry Toolkit untuk Visual Studio Code keduanya menggunakannya.

Skema muncul dalam dua konteks file dengan konvensi penamaan yang berbeda:

agent.manifest.yaml adalah AgentManifest, templat berparameter yang digunakan oleh sampel warisan. Inisialisasi azure.yaml saat ini azd ai agent init -t memerlukan dokumen proyek dan menolak pembungkus AgentManifest.
agent.yaml adalah AgentDefinition, konfigurasi konkret yang ditulis inisialisasi warisan ke dalam proyek Anda di src/<agent>/agent.yaml.

Kedua file menjelaskan apa itu agen: model, alat, protokol, lingkungan, dan sumber dayanya. Ini berbeda dari azure.yaml, yang menjelaskan cara memprovisikan dan menyebarkan sumber daya Azure. azure.yaml Untuk referensi, lihat referensi azure.yaml untuk agen yang dihosting.

Jenis skema

AgentDefinition

AgentDefinition adalah spesifikasi konkret dari agen yang siap dijalankan. Ini menjelaskan satu instans agen dengan konfigurasi tertentu dan tanpa {{ parameter }} tempat penampung templat.

Setiap AgentDefinition memiliki kind bidang yang menentukan jenis agen.

Kind	Deskripsi
`prompt`	Agen berbasis perintah dikonfigurasi hanya melalui instruksi.
`hosted`	Agen kontainer yang disebarkan sebagai gambar kontainer.
`workflow`	Agen orkestrasi yang mengoordinasikan agen lain.

AgentDefinition yang dihasilkan masih dapat berisi ${VAR_NAME} referensi. Ini adalah azd tempat penampung variabel lingkungan, bukan bagian dari spesifikasi AgentSchema. Mereka memungkinkan file definisi tunggal bekerja di beberapa azd lingkungan dengan menyelesaikan nilai dari file setiap lingkungan .azure/<env>/.env pada waktu penyebaran.

AgentManifest

AgentManifest adalah templat berparameter untuk membuat agen secara dinamis. Ini membungkus AgentDefinition sebagai bidangnya template dan menambahkan:

parameters: nilai yang diminta atau disuntikkan pada waktu pembuatan, menggunakan {{ parameter }} sintaks substitusi.
resources: dependensi eksternal seperti penyebaran model, kotak alat, atau koneksi.

Gunakan AgentManifest saat Anda memerlukan templat yang dapat digunakan kembali atau ingin menyebarkan agen serupa dengan konfigurasi yang berbeda. Saat menjalankan azd ai agent init, Anda biasanya mengarahkan ke manifes, baik dengan memilih templat atau menyediakan URL. Proses init meminta nilai parameter dan menghasilkan AgentDefinition.

ContainerAgent

ContainerAgent adalah AgentDefinition dengan kind: hosted. Ini memperluas definisi dasar dengan bidang khusus kontainer dan merupakan bagian template dalam AgentManifest saat Anda membangun agen yang dihosting.

Kapan menggunakan manifes atau definisi

Gunakan manifes saat	Menggunakan definisi saat
Anda menerbitkan templat agen yang dapat digunakan kembali bagi orang lain untuk membuat instans.	Anda menyebarkan agen tujuan tunggal tertentu.
Anda ingin pengguna mengonfigurasi model, alat, atau koneksi pada waktu init.	Semua nilai konfigurasi diketahui dan diperbaiki.
Anda membuat sampel atau templat pemula.	Anda sudah menjalankan `azd ai agent init` dan memiliki definisi yang dihasilkan.

Sebagian besar pengembang mulai dari manifes melalui azd ai agent init lalu bekerja dengan definisi yang dihasilkan. Penulis templat dan penerbit sampel adalah pembuat utama manifes.

Bidang tingkat atas

Referensi di bawah ini men dokumen bidang manifes, yang merupakan superset dari bidang definisi.

Bidang	Tipe	Required	Deskripsi
`name`	string	Yes	Nama manifes agen.
`description`	string	No	Deskripsi agen.
`metadata`	objek	No	Metadata tambahan, seperti `tags`.
`template`	ContainerAgent	Yes	Templat definisi agen.
`parameters`	objek	No	Parameter yang dapat dikonfigurasi diminta selama init.
`resources`	array	Yes	Sumber daya yang diperlukan oleh agen.

templat (ContainerAgent)

Bidang template menentukan agen kontainer yang dihosting.

Bidang	Tipe	Required	Deskripsi
`name`	string	Yes	Nama agen.
`kind`	string	Yes	Harus untuk agen yang dihosting `hosted` .
`protocols`	array	Yes	Dukungan protokol.
`environment_variables`	array	No	Variabel lingkungan untuk kontainer.
`resources`	objek	No	CPU kontainer dan sumber daya memori.
`image`	string	No	Jalur gambar kontainer bawaan.
`dockerfilePath`	string	No	Jalur ke Dockerfile.

Protokol

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

Protocol	Deskripsi
`responses`	OpenAI Responses API. Termasuk manajemen riwayat percakapan.
`invocations`	Protokol payload kustom. Tidak ada manajemen percakapan bawaan.

Untuk spesifikasi protokol lengkap, lihat Kontrak runtime agen yang dihosting.

environment_variables

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

Sintaks mereferensikan ${ }azd variabel lingkungan dari .azure/<env>/.env.

Note

Jangan mendeklarasikan FOUNDRY_PROJECT_ENDPOINT dalam environment_variables. Platform ini menyuntikkannya secara otomatis ke dalam kontainer yang dihosting, dan azd ai agent run mengaturnya untuk pengembangan lokal. Mendeklarasikannya di sini berlebihan dan berisiko membayangi nilai platform.

parameters

Parameter diminta selama azd ai agent init. Gunakan secret: true untuk nilai sensitif.

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

resources

Sumber daya menentukan apa yang dibutuhkan agen. Bentuk di bawah ini menjelaskan manifes apa yang dinyatakan dan apa yang azd ai agent init ditulis ke dalam proyek Anda. Setelah init, kelola sumber daya cakupan proyek yang sama saat runtime dengan perintah CLI langsung: azd ai connection, , azd ai toolboxazd ai skill, dan azd ai routine.

Note

Skema tidak menyertakan bidang keterampilan. azd ai agent initPerintah , azd ai agent run, dan azd up tidak mengunduh keterampilan secara otomatis. Kelola keterampilan sebagai sumber daya tingkat proyek dengan azd ai skill dan kawat sendiri ke runtime agen Anda.

Sumber daya model

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

Sumber daya koneksi

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

Sumber daya kotak alat

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 }}"

Versi kotak alat membawa tiga jenis entri: entri mentah tools (kemampuan bawaan seperti web-search atau code-interpreter), connections (koneksi proyek seperti server MCP alat jarak jauh atau indeks pencarian), dan skills (referensi ke keterampilan proyek yang ada). Slot tools dinyatakan di depan dalam manifes. Tambahkan koneksi dan referensi keterampilan secara bertahap dengan azd ai toolbox connection add dan azd ai toolbox skill add.

Contoh lengkap

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 }}"

Substitusi variabel

Penggantian terjadi dalam dua lapisan: parameter manifes diselesaikan pada waktu init, dan variabel lingkungan diselesaikan pada waktu proses atau penyebaran. Satu file definisi kemudian dapat berfungsi di semua lingkungan Anda azd .

Syntax	Diselesaikan ketika	Oleh apa
`{{ param_name }}`	`azd ai agent init`	Nilai parameter manifes yang diminta dari pengguna.
`${VAR_NAME}`	`azd deploy` atau `azd ai agent run`	`azd` variabel lingkungan dari `.azure/<env>/.env`.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-07-07

referensi skema agent.yaml

Jenis skema

AgentDefinition

AgentManifest

ContainerAgent

Kapan menggunakan manifes atau definisi

Bidang tingkat atas

templat (ContainerAgent)

Protokol

environment_variables

parameters

resources

Sumber daya model

Sumber daya koneksi

Sumber daya kotak alat

Contoh lengkap

Substitusi variabel

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: