Informazioni di riferimento sullo schema agent.yaml

Importante

Gli elementi contrassegnati come anteprima in questo articolo sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio e Microsoft non lo consiglia per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

Annotazioni

I manifesti dell'agente (agent.manifest.yaml) e le definizioni degli agenti autonomi (agent.yaml) sono deprecati. A partire dalle estensioni Foundry azd (azure.ai.agents 1.0.0-beta.1), tutte le configurazioni dell'agente ospitato si trovano in un singolo azure.yamloggetto . Vedere Creare azure.yaml per gli agenti ospitati e informazioni di riferimento su azure.yaml per gli agenti ospitati.

La specifica AgentSchema è uno standard aperto per la definizione degli agenti di intelligenza artificiale. Quando si compilano agenti ospitati, si lavora principalmente con tre tipi di schema di primo livello: AgentDefinition, AgentManifest e ContainerAgent. Questo modello di schema legacy per AgentManifest, AgentDefinition, agent.manifest.yamle agent.yaml viene conservato per riferimento e viene sostituito da azure.yaml. Lo schema non è specifico di uno strumento. L'interfaccia della riga di comando per sviluppatori Azure (azd) e Microsoft Foundry Toolkit per Visual Studio Code entrambi lo usano.

Lo schema viene visualizzato in due contesti di file con convenzioni di denominazione distinte:

  • agent.manifest.yaml è un AgentManifest, un modello con parametri usato dagli esempi legacy. L'inizializzazione corrente azd ai agent init -t richiede un azure.yaml documento di progetto e rifiuta i wrapper AgentManifest.
  • agent.yaml è un AgentDefinition, la configurazione concreta che l'inizializzazione legacy ha scritto nel progetto in src/<agent>/agent.yaml.

Entrambi i file descrivono che cos'è un agente: il modello, gli strumenti, i protocolli, l'ambiente e le risorse. Questo valore è diverso da azure.yaml, che descrive come effettuare il provisioning e distribuire le risorse Azure. Per informazioni di azure.yaml riferimento, vedere azure.yaml reference for hosted agents (Informazioni di riferimento su azure.yaml per gli agenti ospitati).

Tipi di schema

AgentDefinition

AgentDefinition è una specifica concreta di un agente pronto per l'esecuzione. Descrive una singola istanza dell'agente con una configurazione specifica e nessun {{ parameter }} segnaposto modello.

Ogni AgentDefinition ha un kind campo che determina il tipo di agente.

Kind Descrizione
prompt Un agente basato su prompt configurato solo tramite istruzioni.
hosted Un agente in contenitori distribuito come immagine del contenitore.
workflow Agente di orchestrazione che coordina altri agenti.

Un AgentDefinition generato può comunque contenere ${VAR_NAME} riferimenti. Si tratta di azd segnaposto di variabili di ambiente, non parte della specifica AgentSchema. Consentono il funzionamento di un singolo file di definizione in più azd ambienti risolvendo i valori del file di ogni ambiente in fase di .azure/<env>/.env distribuzione.

AgentManifest

AgentManifest è un modello con parametri per la creazione dinamica degli agenti. Esegue il wrapping di agentDefinition come campo template e aggiunge:

  • parameters: valori richiesti o inseriti in fase di creazione, usando la {{ parameter }} sintassi di sostituzione.
  • resources: dipendenze esterne, ad esempio distribuzioni di modelli, casella degli strumenti o connessioni.

Usare agentManifest quando sono necessari modelli riutilizzabili o si vogliono distribuire agenti simili con configurazioni diverse. Quando si esegue azd ai agent init, in genere si punta a un manifesto selezionando un modello o fornendo un URL. Il processo init richiede i valori dei parametri e genera un AgentDefinition.

ContainerAgent

ContainerAgent è un AgentDefinition con kind: hosted. Estende la definizione di base con campi specifici del contenitore ed è all'interno template di un AgentManifest quando si compila un agente ospitato.

Quando usare un manifesto o una definizione

Usare un manifesto quando Usare una definizione quando
Si pubblica un modello di agente riutilizzabile per consentire ad altri utenti di creare un'istanza. Si distribuisce un agente specifico a scopo singolo.
Si vuole che gli utenti configurino il modello, gli strumenti o le connessioni in fase di init. Tutti i valori di configurazione sono noti e fissi.
Si compila un modello di esempio o starter. È già stata eseguita azd ai agent init e si dispone di una definizione generata.

La maggior parte degli sviluppatori inizia da un manifesto e azd ai agent init quindi usa la definizione generata. Gli autori di modelli e gli editori di esempio sono i creatori principali dei manifesti.

Campi di primo livello

Il riferimento seguente documenta i campi manifesto, che sono un superset dei campi di definizione.

Field Tipo Obbligatorio Descrizione
name string Sì Nome del manifesto dell'agente.
description string No Descrizione dell'agente.
metadata object No Metadati aggiuntivi, ad esempio tags.
template ContainerAgent Sì Modello di definizione dell'agente.
parameters object No Parametri configurabili richiesti durante init.
resources array Sì Risorse richieste dall'agente.

template (ContainerAgent)

Il template campo definisce l'agente contenitore ospitato.

Field Tipo Obbligatorio Descrizione
name string Sì Nome dell'agente.
kind string Sì Deve essere hosted per gli agenti ospitati.
protocols array Sì Supporto del protocollo.
environment_variables array No Variabili di ambiente per il contenitore.
resources object No Risorse di CPU e memoria del contenitore.
image string No Percorso predefinito dell'immagine del contenitore.
dockerfilePath string No Percorso del Dockerfile.

Protocolli

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0
Protocol Descrizione
responses API Risposte OpenAI. Include la gestione della cronologia delle conversazioni.
invocations Protocollo payload personalizzato. Nessuna gestione delle conversazioni predefinita.

Per la specifica completa del protocollo, vedere Contratto di runtime dell'agente ospitato.

environment_variables

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

La ${ } sintassi fa riferimento alle azd variabili di ambiente da .azure/<env>/.env.

Annotazioni

Non dichiarare FOUNDRY_PROJECT_ENDPOINT in environment_variables. La piattaforma lo inserisce automaticamente in contenitori ospitati e azd ai agent run lo imposta per lo sviluppo locale. Dichiararlo qui è ridondante e rischia di nascondere il valore della piattaforma.

parameters

I parametri vengono richiesti durante azd ai agent init. Usare secret: true per i valori sensibili.

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

risorse

Le risorse definiscono le esigenze dell'agente. Le forme seguenti descrivono quali manifesti dichiarano e cosa azd ai agent init scrive nel progetto. Dopo init, gestire le stesse risorse con ambito progetto in fase di esecuzione con comandi diretti dell'interfaccia della riga di comando: azd ai connection, azd ai toolbox, azd ai skille azd ai routine.

Annotazioni

Lo schema non include un campo di competenze. I azd ai agent initcomandi , azd ai agent rune azd up non scaricano automaticamente le competenze. Gestire le competenze come risorse a livello di progetto e azd ai skill collegarle al runtime dell'agente manualmente.

Risorsa modello

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

Risorsa di connessione

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

Risorsa casella degli strumenti

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

Una versione della casella degli strumenti include tre tipi di voci: voci non tools elaborate (funzionalità predefinite come web-search o code-interpreter), connections (connessioni di progetto come un server MCP remoto o un indice di ricerca) e skills (riferimenti alle competenze esistenti del progetto). Lo tools slot viene dichiarato in primo piano nel manifesto. Aggiungere connessioni e riferimenti alle competenze in modo incrementale con azd ai toolbox connection add e azd ai toolbox skill add.

Esempio completo

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

Sostituzione di variabili

La sostituzione avviene in due livelli: i parametri manifesto vengono risolti init time e le variabili di ambiente vengono risolte in fase di esecuzione o distribuzione. Un file di definizione può quindi funzionare in tutti gli azd ambienti.

Sintassi Risolto quando Per cosa
{{ param_name }} azd ai agent init I valori dei parametri del manifesto richiesti dall'utente.
${VAR_NAME} azd deploy oppure azd ai agent run azd variabili di ambiente da .azure/<env>/.env.

Contenuti correlati

  • Ultimo aggiornamento: