Mengimpor agen deklaratif Microsoft Agent Framework
Panduan langkah demi langkah ini mengimpor agen deklaratif Microsoft Agent Framework — asisten yang menjawab pertanyaan dari dokumentasi yang dicarinya melalui server MCP — dan membangun aplikasi untuk Docker Compose. Impor menyusun draf setiap file yang dibaca oleh build: agen dan modelnya, kunci yang disajikan agen kepada model sebagai referensi variabel, dan realisasi masing-masing. Impor menanyakan satu kali satu-satunya nilai yang tidak dimuat oleh agen deklaratif mana pun, yaitu image tempat aplikasi Anda berjalan. Setiap file dan setiap blok keluaran di bawah berasal dari eksekusi nyata; agen deklaratif dan setiap tahap panduan ini ada di contoh import-agent-framework, tempat skrip pemeriksaan menjalankan impor lagi, membandingkan apa yang ditulisnya, apa yang dicetaknya, dan blok yang dikutip halaman ini dengan file yang disimpan di sana, serta memvalidasi dan membangun apa yang ditulis impor.
Membuat contoh
Anda dapat menjalankan impor ini dengan perintah di halaman ini, atau meminta asisten AI Anda menjalankannya untuk Anda.
Tulis contoh ke folder baru yang dinamai sesuai contoh itu:
aggrega scaffold --example import-agent-frameworkKemudian ia mencetak perintah yang dijalankan berikutnya. Perintah pertama berpindah ke folder baru; perintah sesudahnya, di bawah, berpindah ke folder source milik folder baru itu, yang berisi apa yang diimpor halaman ini dan merupakan tempat impor dijalankan:
cd import-agent-framework
Proyek
Aplikasi yang dibangun di atas Agent Framework dapat memuat agen dari agen deklaratif: dokumen YAML berjenis Prompt yang menyebutkan model agen, instruksinya, dan alat-alatnya. Dokumen ini, yang ditulis untuk panduan ini, menyebutkan gpt-4.1-mini milik OpenAI dan server MCP yang diterbitkan Microsoft Learn:
kind: Promptname: SupportAgentdisplayName: Support Assistantdescription: Answers a customer's question about the product from its documentation.instructions: You answer customers' questions about the product, from its documentation only.model: id: gpt-4.1-mini provider: OpenAI apiType: Responses options: temperature: 0.2 connection: kind: key key: =Env.OPENAI_API_KEYtools: - kind: mcp name: microsoft_learn description: Search Microsoft's documentation on Microsoft Learn. url: https://learn.microsoft.com/api/mcp approvalMode: kind: never allowedTools: - microsoft_docs_search - microsoft_docs_fetchKunci model ditulis sebagai =Env.OPENAI_API_KEY, sehingga file tidak memuat kunci apa pun. Agent Framework membaca ekspresi itu dari variabel lingkungan OPENAI_API_KEY hanya jika aplikasi memuat agen deklaratif dengan AgentFactory(safe_mode=False), pengaturan keamanan milik Agent Framework sendiri, dan runtime .NET tersedia; jika tidak, kuncinya adalah teks ekspresi sebagaimana tertulis. Kode aplikasi, yang memuat agen deklaratif, tidak pernah dibaca oleh impor, dan bukan bagian dari contoh. Di samping file tersebut, sebuah .aggrega-config.yaml menjadikan folder itu ruang kerja:
# The workspace key marks this directory as the workspace root, so an import run# here writes its drafts beside support-agent.yaml.workspace: {}# The registry the importer is fetched from the first time an import needs it.default_registry: hub.aggrega.aiImpor mereferensikan Components agen Agent Framework dan model OpenAI dari katalog, dan --target menyusun draf Manifest dari Recipes katalog tersebut. Ruang kerja tidak menyebutkan folder katalog apa pun, jadi impor membaca katalog pustaka standar dari registri tempat ia mengambil pengimpornya: snapshot bertanda tangan dari katalog yang diterbitkan, yang diambil, diverifikasi, dan disimpan di cache konten ruang kerja oleh impor pertama, serta disebutkan dengan digest-nya dalam catatan yang ditulis impor di samping drafnya. Ruang kerja yang menyebutkan folder katalognya sendiri — di AGGREGA_CATALOG_DIRS, atau di bawah workspace.catalog_dirs — mengimpor terhadap folder-folder itu sebagai gantinya.
Apa yang ditanyakan impor
Agen deklaratif menyebutkan modelnya, tidak pernah image tempat aplikasi berjalan: image itu Anda bangun dari proyek Anda. Katalog tidak menyimpan image default untuk aplikasi yang dibangun di atas Agent Framework, sehingga impor menanyakannya. Saat dijalankan di terminal tanpa jawaban yang tersedia, impor bertanya:
The drafts leave values empty that the source cannot hold. Answer each one, or press Enter to leave it for later in the answers file:
release.yaml spec.components.supportagent.infra.image Container image running the application built on Microsoft Agent Framework.>lalu menulis jawabannya ke dalam draf dan ke import-answers.yaml, di samping support-agent.yaml, sehingga impor berikutnya membacanya dari sana dan tidak menanyakan apa pun. Tanpa terminal — dalam integrasi berkelanjutan, atau melalui pipe — impor tidak menanyakan apa pun: impor menulis file dengan kunci kosong, lalu berhenti sambil menyebutkan file tersebut. Contoh ini sudah memuat file tersebut, dengan image yang telah dijawab, ghcr.io/example/support-agent:1.0.0, yang mewakili image yang Anda bangun:
# Values the import could not draft from the source, keyed by the drafted file and the key path inside# it. Write each one beside its key; an import of the same source, and a sync, read them from here and# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable# name, ${NAME}, or the name of a Kubernetes Secret.release.yaml: # Container image running the application built on Microsoft Agent Framework. spec.components.supportagent.infra.image: "ghcr.io/example/support-agent:1.0.0" # The origin of the secret value, written by the operator in the Release. Read exactly as # values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes # from, never the value. spec.components.supportagent.uses.model.gpt-4-1-mini.features.credential.infra.origin: "openai-api-key"Jawaban kedua ditujukan untuk build bagi Kubernetes, dengan --target helm: di sana agen membaca kunci OpenAI dari Secret Kubernetes, dan jawabannya adalah nama Secret tersebut, openai-api-key, bukan kuncinya. Build untuk Docker Compose justru membaca kunci dari shell Anda, sehingga impor ini tidak menggunakan jawaban itu. File jawaban impor menjelaskan file tersebut, pertanyaannya, dan aturan untuk jawaban sebuah rahasia.
aggrega import mencantumkan setiap flag yang diterima perintah ini, termasuk --answers, yang menyebutkan file jawaban yang disimpan di tempat lain.
Pindah ke source:
cd sourceMenjalankan impor
Sebutkan file agen deklaratif. Impor membaca setiap agen deklaratif sebagai file tersendiri dan tidak pernah sebagai direktori:
aggrega import support-agent.yaml --target composePada keluaran standar, impor mencantumkan apa yang ditulisnya:
wrote aggregate.yamlwrote release.yamlwrote manifest.yamlwrote .aggrega-import.jsonPada galat standar, dengan <workspace> mewakili folder tempat Anda menjalankannya:
[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]read as the agent-framework format, with drafted paths relative to <workspace>warn: the value of tools.microsoft_learn.url of node SupportAgent is carried as written in the Release the draft writes: the field belongs to an MCP server's configuration, which can carry a key, and setting empty_credentials to marked or all writes it emptyinfo: the answers file <workspace>/import-answers.yaml also answers spec.components.supportagent.uses.model.gpt-4-1-mini.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not appliedmapped SupportAgent (agent) to core/ai-agent/agent-framework as a reference, NONEmapped gpt-4.1-mini (model) to core/ai-model/openai as a reference, NONEmade no choice for SupportAgent#microsoft_learn (tool)Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)
- Baris
warnmenyebutkan nilai yang dapat memuat kunci — alamat server MCP — dan menyatakan bahwa nilai itu dibawa sebagaimana tertulis. Alamat ini tidak memuat kunci apa pun. - Baris
infomenyebutkan jawaban yang tidak digunakan oleh draf Docker Compose, yang disimpan di file jawaban untuk build bagi Kubernetes. - Baris-baris
mappedmenyatakan bahwa agen adalah instans dari agen Agent Framework pustaka standar,core/ai-agent/agent-framework, dan modelnya instans daricore/ai-model/openai. Tingkatnya tertulisNONE: impor Agent Framework mereferensikan Components ini berdasarkan apa yang disebutkan agen deklaratif, bukan dengan membandingkan masing-masing dengan katalog. - Baris
made no choiceadalah server MCP, yang tidak didrafkan oleh impor sebagai Component apa pun, dengan alasan yang diberikan komentar diaggregate.yaml. - Baris
Pull completeadalah impor yang mengambil apa yang menjadi dependensi Release yang dirancang, seperti yang dilakukanaggrega pull, ke dalamrelease.lock, sehingga draf dapat langsung divalidasi dan di-build. Dengan--offline, impor tidak mengambil apa pun dan menyebutkan perintahaggrega pullyang perlu dijalankan.
Apa yang ditulisnya
Aggregate, Release, dan Manifest diberi nama imported/supportagent, berdasarkan name milik agen, SupportAgent, yang disingkat menjadi supportagent — displayName miliknya tidak dibaca — di bawah namespace yang ditetapkan oleh pengaturan target_namespace milik pengimpor, yaitu imported kecuali Anda menetapkan yang lain (Pengaturan).
aggregate.yaml — agen, yang tersambung ke modelnya dengan kunci yang disajikannya dideklarasikan pada koneksi, serta model tersebut:
# Not read: the application's code, which loads each declarative agent and binds the functions of its function tools; the application runs in the image the Release names for each instance, and loads its declarative agents itself.apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: imported/supportagent version: 0.1.0 description: Draft Aggregate imported from a source in the agent-framework format.spec: components: # The declarative agent SupportAgent. # Read by the application from the declarative agent, and taken by no key of core/ai-agent/agent-framework: instructions, the options of its model requests (temperature). # The MCP server microsoft_learn, drafted as no Component and no connection, since Agent Framework sends it to the model's provider as a hosted tool, and the provider, not the application, reaches it at its url, which must therefore be reachable from the provider; its url is written above supportagent's entry in the Release. # Stated by the declarative agent for microsoft_learn: its description, "Search Microsoft's documentation on Microsoft Learn."; its approval mode, never; the tools of the server it allows, microsoft_docs_search, microsoft_docs_fetch. supportagent: type: core/ai-agent/agent-framework values: display_name: "Support Assistant" description: "Answers a customer's question about the product from its documentation." uses: model: gpt-4-1-mini: target: gpt-4-1-mini # For the compose target, the lines below declare credential on gpt-4-1-mini: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none. features: credential: type: core/secret-value values: key: OPENAI_API_KEY # The model gpt-4.1-mini, which SupportAgent names with the OpenAI provider. gpt-4-1-mini: type: core/ai-model/openai values: model: "gpt-4.1-mini"Server MCP bukan Component dan bukan koneksi agen: Agent Framework mengirimkannya ke penyedia model sebagai alat yang di-hosting, dan penyedia, bukan aplikasi, yang menjangkaunya di url-nya, sehingga alamat itu harus dapat dijangkau dari penyedia. Instruksi, opsi permintaan ke model, serta deskripsi, mode persetujuan, dan alat yang diizinkan dari server tetap berada di agen deklaratif, yang dibaca oleh aplikasi; komentar menyebutkan masing-masing. API OpenAI adalah layanan yang di-hosting, sehingga Component agen menolak koneksi ke sana yang tidak membawa kredensial apa pun; koneksi tersebut mendeklarasikan satu kredensial, di bawah kunci OPENAI_API_KEY, yaitu variabel tempat agen deklaratif membaca kuncinya.
release.yaml — lingkungan, image, port yang dipublikasikan, dan asal kunci:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: imported/supportagent # environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to. environment: development version: 0.1.0 description: Draft Release imported from a source in the agent-framework format.spec: aggregate: imported/supportagent manifest: imported/supportagent components: # The declarative agent also states these values for its model and its MCP servers, written here for review: # - model.connection.key, written as =Env.OPENAI_API_KEY, which Agent Framework reads from the environment variable OPENAI_API_KEY only where the application loads the declarative agent with AgentFactory(safe_mode=False), Agent Framework's own security setting, and a .NET runtime is present; otherwise the value is the expression's text as written # - tools.microsoft_learn.url: "https://learn.microsoft.com/api/mcp" supportagent: infra: # Left for the Release, since the source cannot supply it: infra.image, the container image running the application built on Agent Framework, holding its declarative agent image: "ghcr.io/example/support-agent:1.0.0" # Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal. published_port: 8000 uses: model: gpt-4-1-mini: features: credential: type: core/secret-value infra: # Attached by reference, never as a value: the credential supportagent presents to gpt-4-1-mini on its model connection, read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value. origin: "${OPENAI_API_KEY}" gpt-4-1-mini: {}Lingkungan, development, adalah nilai bawaan yang ditulis impor karena tidak ada agen deklaratif yang menyebutkan lingkungan; ubah nilai itu jika Release di-deploy ke tempat lain. Image adalah jawaban yang dibaca impor dari import-answers.yaml. Agen dipublikasikan di alamat loopback mesin Anda, pada port 8000, dan meneruskan ke port tempat programnya mendengarkan, infra.port, 8000 kecuali Anda menetapkannya. Kunci adalah referensi variabel ${OPENAI_API_KEY}, dinamai sesuai variabel yang dibaca agen deklaratif, tidak pernah berupa nilai. Alamat server MCP ditulis sebagaimana dinyatakan agen deklaratif, untuk ditinjau, dan tidak ditetapkan di tempat lain: Agent Framework menyerahkannya kepada penyedia dalam permintaannya ke model.
manifest.yaml — Recipe Compose untuk agen dan model, serta realisasi yang menulis referensi variabel kunci ke dalam file Compose sebagaimana tertulis:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: imported/supportagent version: 0.1.0spec: mappings: components: type: core/ai-agent/agent-framework: compose/agent-framework core/ai-model/openai: compose/openai features: type: core/secret-value: compose/dotenv-secretrelease.lock mencatat entitas katalog tempat Release diselesaikan, berdasarkan digest, dan .aggrega-import.json adalah catatan tentang apa yang ditulis impor, yang dibaca oleh aggrega import --sync berikutnya.
Validasi dan build
aggrega validate --release release.yamlaggrega build --release release.yaml

Validasi mencetak:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)release dependency validation passed: release.yaml (schema-pillar + dependency pillars)dan build, dengan <workspace> mewakili folder tempat Anda menjalankannya:
notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: a total build time, which differs per run]Build completed: 1 file written to <workspace>/distBaris notice hanya bersifat informatif: Feature rahasia menerima nilai origin miliknya dari values milik Aggregate atau infra milik Release, dan pemberitahuan itu melaporkan bahwa satu daun dideklarasikan di keduanya. Pemberitahuan ini tidak mengubah putusan apa pun.
Layanan agen di dist/compose/docker-compose.yaml:
services: supportagent: image: ghcr.io/example/support-agent:1.0.0 environment: OPENAI_BASE_URL: https://api.openai.com/v1 OPENAI_MODEL: gpt-4.1-mini OPENAI_API_KEY: ${OPENAI_API_KEY} ports: - 127.0.0.1:8000:8000 [… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version] networks: - composeAplikasi menerima alamat model, namanya, dan kuncinya dalam variabel yang dibaca klien OpenAI milik Agent Framework, sehingga =Env.OPENAI_API_KEY milik agen deklaratif membaca kunci yang dilampirkan Release di tempat aplikasi memuat agen seperti yang dijelaskan Proyek. Tidak ada variabel yang membawa alamat server MCP, yang dijangkau oleh penyedia. Model tidak mendapat layanan sendiri: agen menjangkau API OpenAI di alamat API itu sendiri. Kunci adalah referensi variabel, yang diisi dari shell Anda saat stack dimulai. Layanan memublikasikan port-nya hanya di 127.0.0.1.
Dengan asisten AI
Asisten AI yang disiapkan dengan alat-alat Aggrega dapat melakukan hal yang sama: tempelkan prompt ini ke dalamnya.
Gunakan hanya alat Aggrega, dan jangan membuat folder sendiri. Jika folder Workspace belum berisi folder `import-agent-framework`, panggil alat `scaffold` sekali dengan `example` diatur ke `import-agent-framework` dan tanpa `dir`: alat ini menulis contoh ke folder `import-agent-framework` yang baru, yang folder `source`-nya berisi apa yang diimpor halaman ini. Lalu panggil alat `import` dengan `workspace_root` diatur ke `import-agent-framework/source`, `source` diatur ke `support-agent.yaml`, dan `target` diatur ke `compose`: alat ini membaca jawaban yang dibutuhkannya dari `import-answers.yaml` di samping `support-agent.yaml`, menulis drafnya ke `import-agent-framework/source`, dan menarik apa yang dibutuhkan draf tersebut. Lalu panggil alat `validate` dengan `workspace_root` diatur ke `import-agent-framework/source` dan `release` diatur ke `release.yaml`, serta alat `build` dengan `workspace_root` diatur ke `import-agent-framework/source`, `release` diatur ke `release.yaml`, dan `write` diatur ke true. Beri tahu saya file mana yang ditulis build; file tersebut berada di bawah `import-agent-framework/source/dist/`.Membukanya di VS Code
Dengan ekstensi Aggrega untuk Visual Studio Code terpasang, buka folder import-agent-framework/source di VS Code, tempat impor menulis drafnya. Folder tersebut berisi satu Release, yaitu draf release.yaml, sehingga editor memilihnya untuk Anda dan memeriksa draf terhadap Release tersebut saat Anda mengeditnya, menandai apa yang ditemukannya di file dan di panel Problems. Aggrega: Show topology graph, di Command Palette, menggambar komponen Release dan koneksi di antara mereka. Aggrega: Build, Aggrega: Preview build, dan Aggrega: Pull bekerja pada Release yang sama, dan masing-masing juga merupakan tombol di panel Commands pada tampilan Aggrega di activity bar; Build menulis file-filenya ke dist/ di dalam folder tersebut. Menggunakan Aggrega di Visual Studio Code membahas sisanya.
Menjalankannya
Anda membangun image dari proyek, dengan Dockerfile Anda sendiri: kode aplikasi, dengan Agent Framework terpasang dan agen deklaratif di dalamnya. Docker Compose menjalankan perintah milik image itu sendiri sebagai layanan agen, karena Recipe tidak menetapkan perintah apa pun, sehingga perintah itu harus tetap berjalan, dan harus melayani permintaan jika Anda ingin menjangkau agen. Program Anda yang menentukan alamat, rute, dan balasannya.
Eksekusi di bawah ini menggunakan image semacam itu: Python dengan paket agent-framework-core, agent-framework-openai, dan agent-framework-declarative milik Agent Framework, runtime .NET — image tersebut menetapkan DOTNET_ROOT ke direktorinya dan DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml, dan, sebagai perintah image, server HTTP kecil milik program itu sendiri di port 8000. Server memuat agen deklaratif dengan AgentFactory(safe_mode=False), sehingga =Env.OPENAI_API_KEY-nya membaca kunci yang dikirimkan oleh build, dan menjalankan agen sekali untuk setiap POST /ask. Bangun image Anda di root proyek, tulis namanya sebagai pengganti ghcr.io/example/support-agent:1.0.0 di import-answers.yaml, lalu impor lagi dengan --sync, yang menulis jawaban baru ke dalam draf dan melakukan pull lagi; kemudian jalankan build:
docker build -t docs-assistant:local .aggrega import support-agent.yaml --syncaggrega build --release release.yamlDengan docs-assistant:local sebagai jawaban, sinkronisasi menyebutkan satu nilai yang diubahnya, di antara baris-baris yang dicetaknya:
changed spec.components.supportagent.infra.image in release.yamlKemudian atur kunci di shell Anda dan mulai stack:
export OPENAI_API_KEY='your OpenAI key'docker compose -p docs-assistant -f dist/compose/docker-compose.yaml up -d --wait-p memberi nama proyek, seperti yang dijelaskan langkah menjalankan di Cara impor berjalan.
Mengujinya
Permintaan di bawah ini mencapai program yang dijalankan image panduan ini: agen deklaratif di balik server HTTP kecil pada port 8000, yang menjawab POST /ask. Program Anda sendiri menentukan rute dan balasannya sendiri. Kirim permintaan itu ke http://127.0.0.1:8000, alamat yang dipublikasikan published_port, setelah program mendengarkan, beberapa detik setelah stack dimulai:
curl -sS -X POST http://127.0.0.1:8000/ask -H 'Content-Type: application/json' \ -d '{"question": "In one short sentence: what is Azure Container Apps?"}'{"error": "the agent failed: ChatClientException: (\"<class 'agent_framework_openai._chat_client.OpenAIChatClient'> service failed to complete the prompt: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the same error repeated as the exception it wraps]"}Proses ini mengatur OPENAI_API_KEY ke nilai pengganti, sehingga balasannya adalah penolakan OpenAI terhadap nilai itu, yang diteruskan oleh program. Kunci yang ditolak OpenAI adalah nilai pengganti tersebut, ditampilkan dalam bentuk tersamar, sehingga =Env.OPENAI_API_KEY milik agen deklaratif membacanya dari lingkungan yang diberikan build.
Hentikan stack dengan:
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml downDi Kubernetes, impor dengan --target helm dan push image ke registry yang menjadi sumber tarikan cluster Anda, dengan menyebutkannya di import-answers.yaml. Lalu buat Secret openai-api-key dan terapkan build, seperti yang dijelaskan langkah menjalankan di Cara impor berjalan. Deployment agen tidak memiliki Service, jadi teruskan sebuah port lokal ke Deployment itu. Perintah ini berjalan sampai Anda menghentikannya:
kubectl port-forward deploy/supportagent 8000:8000Forwarding from 127.0.0.1:8000 -> 8000Forwarding from [::1]:8000 -> 8000Dari terminal lain, kirim permintaan yang sama ke port yang diteruskan:
curl -sS -X POST http://127.0.0.1:8000/ask -H 'Content-Type: application/json' \ -d '{"question": "In one short sentence: what is Azure Container Apps?"}'{"error": "the agent failed: ChatClientException: (\"<class 'agent_framework_openai._chat_client.OpenAIChatClient'> service failed to complete the prompt: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key, and the same error repeated as the exception it wraps]"}