Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Importare un agente dichiarativo di Microsoft Agent Framework

Questa procedura guidata importa un agente dichiarativo di Microsoft Agent Framework — un assistente che risponde a domande attingendo alla documentazione in cui cerca tramite un server MCP — e compila l’applicazione per Docker Compose. L’importazione redige ogni file che la build legge: l’agente e il suo modello, la chiave che l’agente presenta al modello come riferimento a una variabile, e le realizzazioni di ciascuno. Chiede una sola volta l’unico valore che nessun agente dichiarativo contiene, l’immagine in cui gira la tua applicazione. Ogni file e ogni blocco di output riportati qui sotto provengono da un’esecuzione reale; l’agente dichiarativo e ogni fase della procedura si trovano nell’esempio import-agent-framework, dove uno script di controllo esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file conservati lì, e convalida e compila ciò che l’importazione ha scritto.

Generare l’esempio

Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example import-agent-framework

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:

Terminal window
cd import-agent-framework

La cartella source dell’esempio generato aperta in Visual Studio Code, che mostra il prompt agent SupportAgent con il suo modello OpenAI e il suo strumento MCP Microsoft Learn.

Il progetto

Un’applicazione costruita su Agent Framework può caricare un agente da un agente dichiarativo: un documento YAML di tipo Prompt che indica il modello dell’agente, le sue istruzioni e i suoi strumenti. Questo, scritto per questa procedura guidata, indica gpt-4.1-mini di OpenAI e il server MCP che Microsoft Learn pubblica:

kind: Prompt
name: SupportAgent
displayName: Support Assistant
description: 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_KEY
tools:
- 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_fetch

La chiave del modello è scritta come =Env.OPENAI_API_KEY, quindi il file non contiene alcuna chiave. Agent Framework legge quell’espressione dalla variabile d’ambiente OPENAI_API_KEY solo dove l’applicazione carica l’agente dichiarativo con AgentFactory(safe_mode=False), l’impostazione di sicurezza propria di Agent Framework, ed è presente un runtime .NET; altrimenti la chiave è il testo dell’espressione così com’è scritto. Il codice dell’applicazione, che carica l’agente dichiarativo, non viene mai letto dall’importazione e non fa parte dell’esempio. Accanto al file, un .aggrega-config.yaml rende la cartella un workspace:

# 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.ai

L’importazione fa riferimento ai Components del catalogo per l’agente Agent Framework e il modello OpenAI, e --target redige un Manifest a partire dalle sue Recipes. Lo spazio di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui scarica il proprio importer: uno snapshot firmato del catalogo pubblicato, scaricato, verificato e conservato nella cache dei contenuti dello spazio di lavoro dalla prima importazione, e indicato tramite il suo digest nel registro che l’importazione scrive accanto alle proprie bozze. Uno spazio di lavoro che indica proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, o sotto workspace.catalog_dirs — importa invece rispetto a quelle.

Cosa chiede l’importazione

Un agente dichiarativo indica il proprio modello, mai l’immagine in cui gira l’applicazione: quell’immagine la costruisci a partire dal tuo progetto. Il catalogo non contiene alcuna immagine predefinita per un’applicazione costruita su Agent Framework, quindi l’importazione la chiede. Eseguita in un terminale senza una risposta a disposizione, chiede:

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.
>

e scrive la risposta nelle bozze e in import-answers.yaml, accanto a support-agent.yaml, così l’importazione successiva la legge da lì e non chiede nulla. Senza un terminale — in integrazione continua, o attraverso una pipe — non chiede nulla: scrive il file con la chiave vuota e si ferma, indicando il file. L’esempio contiene già il file, con l’immagine come risposta, ghcr.io/example/support-agent:1.0.0, che rappresenta l’immagine che costruisci:

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

La seconda risposta è per una build per Kubernetes, con --target helm: lì l’agente legge la chiave OpenAI da un Secret di Kubernetes, e la risposta è il nome del Secret, openai-api-key, mai la chiave. Una build per Docker Compose legge invece la chiave dalla tua shell, quindi questa importazione non usa quella risposta. Il file delle risposte dell’importazione descrive il file, le domande e le regole per la risposta a un segreto.

aggrega import elenca ogni flag accettato dal comando, tra cui --answers, che indica un file delle risposte conservato altrove.

Entra in source:

Terminal window
cd source

Eseguire l’importazione

Indica il file dell’agente dichiarativo. L’importazione legge ogni agente dichiarativo come un file a sé stante e mai come una directory:

Terminal window
aggrega import support-agent.yaml --target compose

Sullo standard output elenca ciò che ha scritto:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:

[… 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 empty
info: 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 applied
mapped SupportAgent (agent) to core/ai-agent/agent-framework as a reference, NONE
mapped gpt-4.1-mini (model) to core/ai-model/openai as a reference, NONE
made no choice for SupportAgent#microsoft_learn (tool)
Pull complete: <workspace>/release.lock (entities=8, source_artifacts=0, external_inputs=0)

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest redatti compaiono accanto all’agente dichiarativo, l’output di Aggrega elenca come sono stati mappati l’agente e il suo modello e i file scritti, e una notifica dice che l’importazione ha redatto 3 file, riconosciuti come agent-framework.

  • La riga warn nomina un valore che può contenere una chiave — l’indirizzo di un server MCP — e dice che viene riportato così com’è scritto. Questo indirizzo non ne contiene.
  • La riga info indica la risposta che le bozze per Docker Compose non usano, conservata nel file delle risposte per una build per Kubernetes.
  • Le righe mapped dicono che l’agente è un’istanza dell’agente Agent Framework della libreria standard, core/ai-agent/agent-framework, e il suo modello un’istanza di core/ai-model/openai. Il loro livello è NONE: l’importazione di Agent Framework fa riferimento a questi Components in base a ciò che l’agente dichiarativo nomina, anziché confrontare ciascuno con il catalogo.
  • La riga made no choice è il server MCP, per il quale l’importazione non redige alcun Component, per il motivo indicato dai commenti in aggregate.yaml.
  • La riga Pull complete è l’import che recupera ciò da cui dipende la Release generata in bozza, come fa aggrega pull, in release.lock, così che le bozze si validino e si compilino subito. Con --offline l’import non recupera nulla e indica il comando aggrega pull da eseguire.

Cosa scrive

L’Aggregate, la Release e il Manifest si chiamano imported/supportagent, dal name dell’agente, SupportAgent, ridotto a supportagent — il suo displayName non viene letto — nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).

aggregate.yaml — l’agente, collegato al suo modello con la chiave che presenta dichiarata sulla connessione, e il modello:

# 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/v1beta1
kind: Aggregate
metadata:
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"

Il server MCP non è un Component né una connessione dell’agente: Agent Framework lo invia al provider del modello come strumento ospitato, e il provider, non l’applicazione, lo raggiunge al suo url, che deve quindi essere raggiungibile dal provider. Le istruzioni, le opzioni delle richieste al modello, e la descrizione, la modalità di approvazione e gli strumenti consentiti del server restano nell’agente dichiarativo, che l’applicazione legge; i commenti li nominano uno per uno. L’API di OpenAI è un servizio ospitato, quindi il Component dell’agente rifiuta una connessione verso di essa che non porti alcuna credenziale; la connessione ne dichiara una, sotto la chiave OPENAI_API_KEY, la variabile da cui l’agente dichiarativo legge la sua chiave.

release.yaml — l’ambiente, l’immagine, la porta pubblicata e da dove proviene la chiave:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
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: {}

L’ambiente, development, è un valore predefinito che l’importazione scrive perché nessun agente dichiarativo ne indica uno; cambialo se la Release esegue il deploy altrove. L’immagine è la risposta che l’importazione ha letto da import-answers.yaml. L’agente è pubblicato sull’indirizzo di loopback della tua macchina, sulla porta 8000, e inoltra alla porta su cui ascolta il suo programma, infra.port, 8000 se non la imposti. La chiave è il riferimento a variabile ${OPENAI_API_KEY}, che prende il nome dalla variabile letta dall’agente dichiarativo, mai un valore. L’indirizzo del server MCP è scritto così come lo dichiara l’agente dichiarativo, per la revisione, e non viene impostato altrove: Agent Framework lo passa al provider nella sua richiesta al modello.

manifest.yaml — la Recipe Compose dell’agente e del modello, e la realizzazione che scrive il riferimento a variabile della chiave nel file Compose così com’è scritto:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/supportagent
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/agent-framework: compose/agent-framework
core/ai-model/openai: compose/openai
features:
type:
core/secret-value: compose/dotenv-secret

release.lock registra, per digest, le entità del catalogo in cui la Release si è risolta, e .aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge.

Convalidare e compilare

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release in bozza aperta nell’editor dopo averla validata, con l’output di Aggrega e una notifica che segnalano entrambi che non sono stati trovati problemi.

La build della Release in bozza: nell’Explorer compare una cartella dist, l’output di Aggrega elenca il file Docker Compose scritto e una notifica indica che è stato scritto 1 file.

La convalida stampa:

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)

e la build, dove <workspace> indica la cartella in cui l’hai eseguita:

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>/dist

La riga notice è informativa: la Feature del segreto accetta il suo origin dai values dell’Aggregate o dall’infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.

Il servizio dell’agente in 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:
- compose

L’applicazione riceve l’indirizzo del modello, il suo nome e la sua chiave nelle variabili lette dai client OpenAI di Agent Framework, quindi l’=Env.OPENAI_API_KEY dell’agente dichiarativo legge la chiave che la Release ha collegato, dove l’applicazione lo carica come descritto in Il progetto. Nessuna variabile contiene l’indirizzo del server MCP, che viene raggiunto dal provider. Il modello non ottiene un servizio proprio: l’agente raggiunge l’API di OpenAI al suo stesso indirizzo. La chiave è un riferimento a una variabile, valorizzato dalla tua shell all’avvio dello stack. Il servizio pubblica la sua porta soltanto su 127.0.0.1.

Con un assistente AI

Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.

Usa solo gli strumenti di Aggrega e non creare alcuna cartella da solo. Se la cartella del Workspace non contiene ancora una cartella `import-agent-framework`, chiama una volta lo strumento `scaffold` con `example` impostato su `import-agent-framework` e senza `dir`: scrive l’esempio in una nuova cartella `import-agent-framework`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato su `import-agent-framework/source`, `source` impostato su `support-agent.yaml` e `target` impostato su `compose`: legge le risposte di cui ha bisogno da `import-answers.yaml` accanto a `support-agent.yaml`, scrive le sue bozze in `import-agent-framework/source` e scarica ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato su `import-agent-framework/source` e `release` impostato su `release.yaml`, e lo strumento `build` con `workspace_root` impostato su `import-agent-framework/source`, `release` impostato su `release.yaml` e `write` impostato su true. Dimmi quali file ha scritto la build; si trovano in `import-agent-framework/source/dist/`.

Aprilo in VS Code

Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-agent-framework/source, dove l’importazione ha scritto le sue bozze. La cartella contiene una sola Release, il release.yaml in bozza, quindi l’editor la seleziona per te e controlla le bozze rispetto a quella Release mentre le modifichi, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i suoi file in dist/ all’interno della cartella. Usare Aggrega in Visual Studio Code tratta il resto.

Esecuzione

L’immagine la costruisci tu a partire dal progetto, con un Dockerfile tuo: il codice dell’applicazione, con Agent Framework installato e l’agente dichiarativo al suo interno. Docker Compose esegue il comando proprio dell’immagine come servizio dell’agente, poiché la Recipe non ne imposta alcuno, quindi quel comando deve restare in esecuzione, e deve servire le richieste se vuoi raggiungere l’agente. Il tuo programma decide l’indirizzo, la route e la risposta.

L’esecuzione qui sotto ha usato un’immagine di questo tipo: Python con i pacchetti agent-framework-core, agent-framework-openai e agent-framework-declarative di Agent Framework, un runtime .NET — l’immagine impostava DOTNET_ROOT sulla sua directory e DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml e, come comando dell’immagine, un piccolo server HTTP proprio del programma sulla porta 8000. Il server carica l’agente dichiarativo con AgentFactory(safe_mode=False), quindi il suo =Env.OPENAI_API_KEY legge la chiave fornita dalla build, ed esegue l’agente una volta per ogni POST /ask. Costruisci la tua immagine nella radice del progetto, scrivi il suo nome al posto di ghcr.io/example/support-agent:1.0.0 in import-answers.yaml e importa di nuovo con --sync, che scrive la nuova risposta nelle bozze ed esegue di nuovo il pull; poi esegui la build:

Terminal window
docker build -t docs-assistant:local .
aggrega import support-agent.yaml --sync
aggrega build --release release.yaml

Con docs-assistant:local come risposta, la sincronizzazione indica l’unico valore che ha cambiato, tra le righe che stampa:

changed spec.components.supportagent.infra.image in release.yaml

Poi imposta la chiave nella tua shell e avvia lo stack:

Terminal window
export OPENAI_API_KEY='your OpenAI key'
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml up -d --wait

-p assegna il nome al progetto, come spiega il passo di esecuzione di Come si svolge un’importazione.

Eseguire il test

La richiesta qui sotto raggiunge il programma che esegue l’immagine di questa guida: l’agente dichiarativo dietro un piccolo server HTTP sulla porta 8000, che risponde a POST /ask. Il tuo programma decide la propria route e la propria risposta. Inviala a http://127.0.0.1:8000, l’indirizzo che published_port pubblica, quando il programma è in ascolto, qualche secondo dopo l’avvio dello stack:

Terminal window
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]"}

L’esecuzione ha impostato OPENAI_API_KEY su un segnaposto, quindi la risposta è il rifiuto di OpenAI, inoltrato dal programma. La chiave che OpenAI ha rifiutato è quel segnaposto, mostrato mascherato, quindi =Env.OPENAI_API_KEY dell’agente dichiarativo l’ha letta dall’ambiente che la build fornisce.

Arresta lo stack con:

Terminal window
docker compose -p docs-assistant -f dist/compose/docker-compose.yaml down

Su Kubernetes, importa con --target helm e invia l’immagine a un registry da cui il tuo cluster scarica, indicandola in import-answers.yaml. Poi crea il Secret openai-api-key e applica la build, come descrive il passo di esecuzione di Come si svolge un’importazione. Il Deployment dell’agente non ha alcun Service, quindi inoltra una porta locale verso di esso. Il comando resta in esecuzione finché non lo interrompi:

Terminal window
kubectl port-forward deploy/supportagent 8000:8000
Forwarding from 127.0.0.1:8000 -> 8000
Forwarding from [::1]:8000 -> 8000

Da un altro terminale, invia la stessa richiesta alla porta inoltrata:

Terminal window
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]"}