Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Importer un agent déclaratif Microsoft Agent Framework

Ce tutoriel importe un agent déclaratif de Microsoft Agent Framework — un assistant qui répond à des questions à partir d’une documentation qu’il interroge via un serveur MCP — et compile l’application pour Docker Compose. L’importation rédige chaque fichier que la compilation lit : l’agent et son modèle, la clé que l’agent présente au modèle sous forme de référence de variable, et les réalisations de chacun. Elle demande une seule fois l’unique valeur qu’aucun agent déclaratif ne contient, l’image dans laquelle s’exécute votre application. Chaque fichier et chaque bloc de sortie ci-dessous proviennent d’une exécution réelle ; l’agent déclaratif et chaque étape du tutoriel se trouvent dans l’exemple import-agent-framework, où un script de vérification relance l’importation, compare ce qu’elle écrit, ce qu’elle affiche et les blocs que cite cette page avec les fichiers qui y sont conservés, puis valide et compile ce que l’importation a écrit.

Générer l’exemple

Vous pouvez exécuter cette importation avec les commandes de cette page, ou la faire exécuter par votre assistant IA.

Écrivez l’exemple dans un nouveau dossier qui porte son nom :

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

Elle affiche ensuite les prochaines commandes à exécuter. La première vous place dans le nouveau dossier ; la suivante, ci-dessous, vous place dans le dossier source du nouveau dossier, qui contient ce que cette page importe et où s’exécute l’import :

Terminal window
cd import-agent-framework

Le dossier source de l’exemple généré, ouvert dans Visual Studio Code, montrant le prompt agent SupportAgent avec son modèle OpenAI et son outil MCP Microsoft Learn.

Le projet

Une application construite sur Agent Framework peut charger un agent à partir d’un agent déclaratif : un document YAML de type Prompt qui nomme le modèle de l’agent, ses instructions et ses outils. Celui-ci, écrit pour ce tutoriel, nomme gpt-4.1-mini d’OpenAI et le serveur MCP que publie Microsoft Learn :

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 clé du modèle est écrite =Env.OPENAI_API_KEY, si bien que le fichier ne contient aucune clé. Agent Framework lit cette expression dans la variable d’environnement OPENAI_API_KEY uniquement lorsque l’application charge l’agent déclaratif avec AgentFactory(safe_mode=False), le paramètre de sécurité propre à Agent Framework, et qu’un runtime .NET est présent ; sinon, la clé est le texte de l’expression tel qu’il est écrit. Le code de l’application, qui charge l’agent déclaratif, n’est jamais lu par l’importation et ne fait pas partie de l’exemple. À côté du fichier, un .aggrega-config.yaml fait du dossier un espace de travail :

# 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’importation référence les Components du catalogue pour l’agent Agent Framework et le modèle OpenAI, et --target rédige un Manifest à partir de ses Recipes. L’espace de travail ne nomme aucun dossier de catalogue ; l’importation lit donc le catalogue de la bibliothèque standard depuis le registre dont elle récupère son importeur : un instantané signé du catalogue publié, récupéré, vérifié et conservé dans le cache de contenu de l’espace de travail par la première importation, et nommé par son condensé dans l’enregistrement que l’importation écrit à côté de ses brouillons. Un espace de travail qui nomme ses propres dossiers de catalogue — dans AGGREGA_CATALOG_DIRS, ou sous workspace.catalog_dirs — importe plutôt par rapport à ceux-ci.

Ce que demande l’importation

Un agent déclaratif nomme son modèle, jamais l’image dans laquelle s’exécute l’application : cette image, vous la construisez à partir de votre projet. Le catalogue ne contient aucune image par défaut pour une application construite sur Agent Framework ; l’importation la demande donc. Exécutée dans un terminal sans réponse disponible, elle demande :

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

puis écrit la réponse dans les brouillons et dans import-answers.yaml, à côté de support-agent.yaml, de sorte que l’importation suivante la lit à cet endroit et ne demande rien. Sans terminal — en intégration continue, ou à travers un pipe — elle ne demande rien : elle écrit le fichier avec la clé vide, puis s’arrête en nommant le fichier. L’exemple contient déjà le fichier, avec l’image renseignée, ghcr.io/example/support-agent:1.0.0, qui tient lieu de l’image que vous construisez :

# 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 seconde réponse concerne une compilation pour Kubernetes, avec --target helm : l’agent y lit la clé OpenAI depuis un Secret Kubernetes, et la réponse est le nom du Secret, openai-api-key, jamais la clé. Une compilation pour Docker Compose lit plutôt la clé depuis votre shell ; cette importation n’utilise donc pas cette réponse. Le fichier de réponses de l’importation décrit le fichier, les questions et les règles applicables à la réponse à un secret.

aggrega import liste toutes les options que prend la commande, dont --answers, qui nomme un fichier de réponses conservé ailleurs.

Placez-vous dans source :

Terminal window
cd source

Lancer l’importation

Nommez le fichier de l’agent déclaratif. L’importation lit chaque agent déclaratif comme un fichier à part entière, et jamais comme un répertoire :

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

Sur la sortie standard, elle liste ce qu’elle a écrit :

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

Sur la sortie d’erreur standard, où <workspace> désigne le dossier dans lequel vous l’avez lancée :

[… 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’importation lancée depuis l’éditeur : l’Aggregate, la Release et le Manifest rédigés apparaissent à côté de l’agent déclaratif, la sortie Aggrega indique comment l’agent et son modèle ont été mappés et les fichiers écrits, et une notification indique que l’importation a rédigé 3 fichiers, reconnus comme agent-framework.

  • La ligne warn nomme une valeur susceptible de contenir une clé — l’adresse d’un serveur MCP — et indique qu’elle est reportée telle qu’elle est écrite. Cette adresse n’en contient aucune.
  • La ligne info nomme la réponse que les brouillons Docker Compose n’utilisent pas, conservée dans le fichier de réponses pour une compilation pour Kubernetes.
  • Les lignes mapped indiquent que l’agent est une instance de l’agent Agent Framework de la bibliothèque standard, core/ai-agent/agent-framework, et son modèle une instance de core/ai-model/openai. Leur niveau indique NONE : l’importation Agent Framework référence ces Components d’après ce que nomme l’agent déclaratif plutôt qu’en comparant chacun au catalogue.
  • La ligne made no choice est le serveur MCP, pour lequel l’importation ne rédige aucun Component, pour la raison qu’indiquent les commentaires de aggregate.yaml.
  • La ligne Pull complete correspond à l’import qui récupère ce dont dépend la Release rédigée, comme le fait aggrega pull, dans release.lock, de sorte que les brouillons se valident et se construisent immédiatement. Avec --offline, l’import ne récupère rien et indique la commande aggrega pull à exécuter.

Ce qu’elle écrit

L’Aggregate, la Release et le Manifest sont nommés imported/supportagent, d’après le name de l’agent, SupportAgent, réduit à supportagent — son displayName n’est pas lu —, sous le namespace que fixe le paramètre target_namespace de l’importeur, imported sauf si vous en fixez un autre (Paramètres).

aggregate.yaml — l’agent, câblé à son modèle avec la clé qu’il présente déclarée sur la connexion, et le modèle :

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

Le serveur MCP n’est ni un Component ni une connexion de l’agent : Agent Framework l’envoie au fournisseur du modèle comme outil hébergé, et c’est le fournisseur, et non l’application, qui l’atteint à son url, qui doit donc être joignable depuis le fournisseur. Les instructions, les options des requêtes du modèle, ainsi que la description, le mode d’approbation et les outils autorisés du serveur restent dans l’agent déclaratif, que lit l’application ; les commentaires nomment chacun d’eux. L’API d’OpenAI est un service hébergé, donc le Component de l’agent refuse une connexion vers elle qui ne porte aucun identifiant ; la connexion en déclare un, sous la clé OPENAI_API_KEY, la variable dans laquelle l’agent déclaratif lit sa clé.

release.yaml — l’environnement, l’image, le port publié et la provenance de la clé :

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’environnement, development, est une valeur par défaut que l’importation écrit parce qu’aucun agent déclaratif n’en nomme un ; modifiez-la si la Release est déployée ailleurs. L’image est la réponse que l’importation a lue dans import-answers.yaml. L’agent est publié sur l’adresse de bouclage de votre machine, sur le port 8000, avec renvoi vers le port sur lequel écoute son programme, infra.port, 8000 sauf si vous le définissez. La clé est la référence de variable ${OPENAI_API_KEY}, nommée d’après la variable que lit l’agent déclaratif, jamais une valeur. L’adresse du serveur MCP est écrite telle que l’agent déclaratif l’énonce, pour relecture, et n’est définie nulle part ailleurs : Agent Framework la transmet au fournisseur dans sa requête au modèle.

manifest.yaml — la Recipe Compose de l’agent et du modèle, et la réalisation qui écrit la référence de variable de la clé dans le fichier Compose telle qu’elle est écrite :

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 enregistre, par digest, les entités du catalogue vers lesquelles la Release a été résolue, et .aggrega-import.json est l’enregistrement de ce que l’importation a écrit, que lit un aggrega import --sync ultérieur.

Valider et compiler

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

La Release rédigée par l’importation, ouverte dans l’éditeur après sa validation, avec la sortie d’Aggrega et une notification qui indiquent toutes deux qu’aucun problème n’a été trouvé.

Le build de la Release rédigée : un dossier dist apparaît dans l’Explorateur, la sortie d’Aggrega liste le fichier Docker Compose écrit et une notification indique qu’1 fichier a été écrit.

La validation affiche :

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)

et le build, où <workspace> désigne le dossier dans lequel vous l’avez exécuté :

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 ligne notice est indicative : la Feature de secret accepte son origin depuis les values de l’Aggregate ou l’infra de la Release, et la notice signale qu’une feuille est déclarée dans les deux. Elle ne change aucun verdict.

Le service de l’agent dans 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’application reçoit l’adresse du modèle, son nom et sa clé dans les variables que lisent les clients OpenAI d’Agent Framework, si bien que l’=Env.OPENAI_API_KEY de l’agent déclaratif lit la clé que la Release a attachée, là où l’application charge l’agent comme le décrit Le projet. Aucune variable ne porte l’adresse du serveur MCP, que le fournisseur atteint. Le modèle n’obtient aucun service propre : l’agent atteint l’API OpenAI à sa propre adresse. La clé est une référence de variable, renseignée depuis votre shell au démarrage de la pile. Le service ne publie son port que sur 127.0.0.1.

Avec un assistant IA

Un assistant IA configuré avec les outils d’Aggrega peut faire de même : collez-y ce prompt.

Utilisez uniquement les outils Aggrega et ne créez vous-même aucun dossier. Si le dossier du Workspace ne contient pas encore de dossier `import-agent-framework`, appelez une fois l’outil `scaffold` avec `example` défini sur `import-agent-framework` et sans `dir` : il écrit l’exemple dans un nouveau dossier `import-agent-framework`, dont le dossier `source` contient ce que cette page importe. Appelez ensuite l’outil `import` avec `workspace_root` défini sur `import-agent-framework/source`, `source` défini sur `support-agent.yaml` et `target` défini sur `compose` : il lit les réponses dont il a besoin dans `import-answers.yaml`, à côté de `support-agent.yaml`, écrit ses brouillons dans `import-agent-framework/source` et récupère ce dont ils ont besoin. Appelez ensuite l’outil `validate` avec `workspace_root` défini sur `import-agent-framework/source` et `release` défini sur `release.yaml`, puis l’outil `build` avec `workspace_root` défini sur `import-agent-framework/source`, `release` défini sur `release.yaml` et `write` défini sur true. Indiquez-moi quels fichiers le build a écrits ; ils se trouvent sous `import-agent-framework/source/dist/`.

L’ouvrir dans VS Code

Une fois l’extension Aggrega pour Visual Studio Code installée, ouvrez dans VS Code le dossier import-agent-framework/source, où l’importation a écrit ses brouillons. Le dossier contient une seule Release, le release.yaml rédigé, donc l’éditeur la sélectionne pour vous et vérifie les brouillons par rapport à cette Release à mesure que vous les modifiez, en signalant ce qu’il trouve dans le fichier et dans le panneau Problèmes. Aggrega: Show topology graph, dans la palette de commandes, dessine les composants de la Release et les connexions entre eux. Aggrega: Build, Aggrega: Preview build et Aggrega: Pull agissent sur la même Release, et chacune est aussi un bouton du panneau Commands de la vue Aggrega dans la barre d’activité ; Build écrit ses fichiers dans le dist/ du dossier. Utiliser Aggrega dans Visual Studio Code couvre le reste.

Exécution

Vous construisez l’image à partir du projet, avec votre propre Dockerfile : le code de l’application, avec Agent Framework installé et l’agent déclaratif à l’intérieur. Docker Compose exécute la commande propre de l’image comme service de l’agent, puisque la Recipe n’en définit aucune ; cette commande doit donc continuer à s’exécuter, et doit servir les requêtes si vous voulez atteindre l’agent. Votre programme décide de l’adresse, de la route et de la réponse.

L’exécution ci-dessous a utilisé une telle image : Python avec les paquets agent-framework-core, agent-framework-openai et agent-framework-declarative d’Agent Framework, un runtime .NET — l’image définissait DOTNET_ROOT sur son répertoire et DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 — support-agent.yaml et, comme commande de l’image, un petit serveur HTTP propre au programme sur le port 8000. Le serveur charge l’agent déclaratif avec AgentFactory(safe_mode=False), de sorte que son =Env.OPENAI_API_KEY lit la clé que fournit le build, et exécute l’agent une fois pour chaque POST /ask. Construisez votre image à la racine du projet, écrivez son nom à la place de ghcr.io/example/support-agent:1.0.0 dans import-answers.yaml, et relancez l’importation avec --sync, qui écrit la nouvelle réponse dans les ébauches et refait le pull ; puis lancez le build :

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

Avec docs-assistant:local comme réponse, la synchronisation nomme la seule valeur qu’elle a modifiée, parmi les lignes qu’elle affiche :

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

Définissez ensuite la clé dans votre shell et démarrez la pile :

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

-p nomme le projet, comme l’explique l’étape d’exécution de Déroulement d’une importation.

Tester

La requête ci-dessous atteint le programme qu’exécute l’image de ce guide : l’agent déclaratif derrière un petit serveur HTTP sur le port 8000, qui répond à POST /ask. Votre propre programme décide de sa propre route et de sa réponse. Envoyez-la à http://127.0.0.1:8000, l’adresse que publie published_port, une fois que le programme écoute, quelques secondes après le démarrage de la 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’exécution a défini OPENAI_API_KEY sur une valeur fictive, donc la réponse est le refus d’OpenAI, relayé par le programme. La clé qu’OpenAI a refusée est cette valeur fictive, affichée masquée, donc le =Env.OPENAI_API_KEY de l’agent déclaratif l’a lue dans l’environnement que fournit le build.

Arrêtez la pile avec :

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

Sur Kubernetes, importez avec --target helm et poussez l’image vers un registre depuis lequel votre cluster tire les images, en la nommant dans import-answers.yaml. Créez ensuite le Secret openai-api-key et appliquez le build, comme le décrit l’étape d’exécution de Déroulement d’une importation. Le Deployment de l’agent n’a pas de Service, donc redirigez un port local vers lui. La commande s’exécute jusqu’à ce que vous l’arrêtiez :

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

Depuis un autre terminal, envoyez la même requête au port redirigé :

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