Referência de runtime de agentes serverless

Este artigo fornece a referência de configuração para o runtime dos agentes serverless do Funções do Azure. Para uma visão geral do runtime e orientações sobre quando o utilizar, veja Serverless agents runtime in Funções do Azure.

Referência do ficheiro do agente

Um ficheiro agente (.agent.md) utiliza matéria inicial YAML para configurar o agente, seguido de instruções markdown.

Campos front-matéria

Utilize estes campos introdutórios para configurar um agente:

Configuração do acionador

Cada ficheiro agente suporta um disparador, definido no trigger objeto na matéria inicial.

Tipos de gatilho suportados

A tabela seguinte lista os valores suportados trigger.type , os seus requisitos argse ligações para a referência completa por tipo:

Exemplos de gatilho

Os exemplos seguintes mostram configurações comuns de gatilho:

Gatilho temporizador (funciona diariamente às 15:00 UTC):

trigger:
  type: timer_trigger
  args:
    schedule: "0 0 15 * * *"

Gatilho HTTP:

trigger:
  type: http_trigger
  args:
    route: summarize
    auth_level: FUNCTION

Gatilho de fila:

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

Gatilho do blob:

trigger:
  type: blob_trigger
  args:
    path: uploads/{name}
    connection: AzureWebJobsStorage

Configuração de toda a aplicação (agents.config.yaml)

Use agents.config.yaml para predeterminações de runtime em toda a aplicação que todos os agentes possam herdar. O runtime pode carregar uma aplicação sem este ficheiro. Adiciona-o quando necessitares de definições partilhadas, como uma implementação do modelo, um tempo limite ou um ponto final de execução em sandbox.

Este ficheiro é uma entrada ao nível da aplicação. O runtime também descobre servidores MCP de mcp.json, competências de skills/ e ferramentas de Python personalizadas de tools/. Essas capacidades estão ativadas nos agentes por defeito. Os metadados iniciais do agente podem substituir as predefinições do runtime ou filtrar servidores, capacidades e ferramentas MCP herdados.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Os agentes individuais podem substituir definições suportadas de tempo de execução nos seus próprios metadados iniciais.

Campos de configuração

Use estes campos de topo em agents.config.yaml:

Ordem de resolução

O ambiente de execução determina primeiro os valores a partir dos metadados iniciais do agente, depois de agents.config.yaml, e, em seguida, das definições da aplicação e dos valores predefinidos do ambiente de execução. Valores de string em agents.config.yaml podem referenciar definições de aplicação, como $AZURE_OPENAI_DEPLOYMENT ou $ACA_SESSION_POOL_ENDPOINT.

Mantenha as predefinições do modelo, do tempo de espera e da ferramenta do sistema em agents.config.yaml. Mantenha definições remotas de servidores MCP, incluindo endpoints de servidores MCP a partir de namespaces de conectores, em mcp.json.

Substituição de variáveis

O ambiente de execução pode substituir definições da aplicação e variáveis de ambiente em cadeias de texto no front matter do agente, nos corpos de instruções do agente, agents.config.yaml e mcp.json.

Para substituições, pode usar ou $SETTING_NAME , %SETTING_NAME%que são tratados da mesma forma pelo runtime. Os nomes das variáveis devem começar por uma letra ou sublinhado e podem conter letras, números e sublinhados.

model: $FOUNDRY_MODEL
system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: %ACA_SESSION_POOL_ENDPOINT%

Email the summary to $TO_EMAIL.

{
  "servers": {
    "office365": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL"
    }
  }
}

Regras de substituição:

• Aplica-se a valores de cadeia, incluindo cadeias aninhadas em objetos ou listas. Não se aplica às teclas objeto.
• Os blocos de código delimitados no corpo das instruções dos agentes não são substituídos, pelo que os exemplos podem incluir o texto literal $VALUE ou %VALUE%.
• Uso $$SETTING_NAME ou %%SETTING_NAME%% para marcadores literais em conteúdo substituído.
• As variáveis em falta permanecem inalteradas. Valores vazios resolvem-se para cadeias vazias.
• A substituição é uma passagem simples. A ${SETTING_NAME} sintaxe não é suportada.
• Para desativar a substituição por um agente, defina substitute_variables: false no ficheiro agente. Isto não desativa a substituição em agents.config.yaml ou mcp.json.

Configuração do servidor MCP (mcp.json)

Quando uma aplicação usa servidores MCP remotos, adicione mcp.json à raiz do projeto de aplicação de funções. O runtime descobre, a partir deste ficheiro, servidores HTTP remotos ou servidores MCP HTTP com capacidade de transmissão em fluxo e disponibiliza as respetivas ferramentas aos agentes, em função de quaisquer filtros específicos de cada agente.

Campos de entrada do servidor

Use estes campos em cada servers entrada:

Authentication

Use o âmbito do Azure API Hub quando o agente consome um servidor MCP gerido a partir de um namespace de conectores. Não guarde segredos de utilizador em mcp.json.

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default",
        "client_id": "$O365_MCP_CLIENT_ID"
      }
    }
  }
}

A definição auth.client_id seleciona qual identidade gerida é utilizada para autenticação no servidor MCP. Defina-o como o ID de cliente de uma identidade gerida atribuída a utilizador. Omita-o para usar a identidade gerida atribuída pelo sistema da aplicação de funções no Azure. A identidade selecionada, ou a sua identidade de programador quando a execução é feita localmente, deve estar autorizada a invocar o servidor MCP.

Conectores do Azure

Os conectores permitem que os agentes trabalhem com serviços externos sem código cliente personalizado da API. Por exemplo, um conector Microsoft 365 Outlook pode enviar emails, um conector Teams pode funcionar com mensagens, e outros conectores podem chamar ações em sistemas como Salesforce, SAP ou SQL. Um Espaço de Nomes de Conectores aloja as ligações, triggers e servidores MCP que disponibilizam essas integrações à sua aplicação.

Para utilizar as funcionalidades dos conectores numa aplicação de agentes sem servidor, crie primeiro um recurso Espaço de Nomes do Conector, crie uma conexão ao serviço e autorize essa conexão. Depois escolhe como o agente usa a ligação:

• Os acionadores de conectores iniciam agentes quando algo acontece num serviço conectado, como uma nova mensagem de e-mail, uma mensagem do Teams ou um evento do calendário. Para utilizar um, crie um gatilho no Espaço de Nomes do Conector que utilize a ligação autorizada e, depois, configure o agente com o nome do gatilho e os argumentos dessa definição de gatilho do conector.
• As ferramentas MCP Connector permitem que os agentes chamem ações de serviço, como enviar emails ou atualizar um registo. Para os usar, crie um servidor MCP no Espaço de Nomes do Conector que utilize a ligação autorizada e depois adicione o endpoint do servidor MCP a mcp.json.

Para mais informações, consulte Usar conectores no Funções do Azure.

Competências

Armazene elementos reutilizáveis de prompt em skills/. Ajudam a manter as instruções base do agente pequenas enquanto disponibilizam instruções específicas do domínio quando necessário. O ambiente de execução utiliza o formato Agent Skills.

Formato de habilidade

O ambiente de execução analisa skills/ na pasta raiz do projeto da aplicação de funções e descobre recursivamente as pastas que contêm SKILL.md.

skills/
  incident-response/
    SKILL.md
    triage-checklist.md
    escalation-policy.md

O ficheiro SKILL.md contém metadados iniciais em YAML, seguidos de instruções em Markdown.

---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---

Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).

Regras de autoria

Siga estas orientações ao criar os seus ficheiros de agente e outros recursos do projeto:

• Cada pasta de habilidades deve conter um SKILL.md ficheiro.
• Os name campos e description são obrigatórios.
• Use letras minúsculas, números e hífens simples para os nomes das habilidades. Não use espaços, caracteres de sublinhado, letras maiúsculas, hífens iniciais, hífens finais ou hífens repetidos.
• Os nomes das habilidades devem ser únicos em toda a aplicação.
• A descrição deve explicar tanto o que a habilidade faz como quando o agente deve usá-la. O runtime carrega primeiro os nomes e descrições das habilidades para que o agente possa decidir quando carregar a habilidade completa.
• As competências podem incluir vários ficheiros de markdown na mesma pasta de competências. Consulte os ficheiros Markdown de suporte a partir de SKILL.md utilizando ligações relativas.
• O ambiente de execução dos agentes sem servidor suporta apenas ficheiros Markdown como conteúdo das competências. Se uma competência precisar de comportamento executável, empacota esse código como uma ferramenta Python personalizada e refere-te à ferramenta pelo nome das instruções da competência.

Filtragem de competências por agente

Os agentes herdam todas as competências descobertas por predefinição. Desativar ou excluir competências num ficheiro de agente quando um agente específico não deve usá-las:

skills: false

skills:
  exclude:
    - incident-response

Execução em sandbox

Para execução de código ou automação do navegador, o runtime pode usar sessões dinâmicas do Azure Container Apps. As sessões dinâmicas fornecem ambientes isolados dos pools de sessão. O runtime utiliza sessões de interpretadores de código para fornecer uma execute_python ferramenta aos agentes.

Configuration

Configurar execução em sandbox em agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requisitos

• O pool de sessões deve ser um pool de sessões de interpretador de código Python, por exemplo, um pool criado com --container-type PythonLTS.
• O valor endpoint é o endpoint de gestão do pool de sessões.
• No Azure, a identidade gerida usada pela aplicação de funções deve ter as atribuições de papéis necessárias para executar código no pool de sessões. As sessões do intérprete de código do Azure Container Apps requerem as funções Azure ContainerApps Session Executor e Contributor no conjunto de sessões.
• Ao correr localmente, a identidade do seu programador deve ter o mesmo acesso necessário ao pool de sessões.
• Para usar uma identidade gerida atribuída pelo utilizador para execução em sandbox, defina system_tools.dynamic_sessions_code_interpreter.client_id o ID do cliente da identidade que tem as atribuições de funções necessárias. Se esta definição não estiver configurada, o ambiente de execução utiliza AZURE_CLIENT_ID e, em seguida, a cadeia de credenciais predefinida.

A ferramenta sandbox executa Python numa sessão isolada. Variáveis, importações e ficheiros podem persistir entre chamadas de ferramenta na mesma sessão do agente. Quando não existe o ID de sessão do agente disponível, o runtime usa uma sessão sandbox nova para que execuções não relacionadas não partilhem estado.

Desativação por agente

Os agentes herdam a execução em sandbox quando esta está configurada a nível global. Podes desativar a execução de um agente específico definindo dynamic_sessions_code_interpreter como false no ficheiro do agente.

system_tools:
  dynamic_sessions_code_interpreter: false

Ferramentas personalizadas de Python

Usa ferramentas Python personalizadas quando precisares de lógica específica para apps que as capacidades integradas do runtime não cobrem. Ferramentas personalizadas correm no processo da aplicação de funções, não numa sessão sandbox.

Descoberta de ferramentas

Adicione ficheiros de ferramenta à tools/ pasta na raiz do projeto da aplicação de funções:

tools/
  submit_ticket.py
  lookup_customer.py

O tempo de execução descobre .py ficheiros em tools/ cujos nomes de ficheiro não começam por _. Na versão de pré-visualização atual, o runtime regista a primeira ferramenta suportada em cada ficheiro. Use uma ferramenta por ficheiro para manter a descoberta previsível.

Definição de ferramentas

Defina uma ferramenta decorando uma função com @tool do pacote de tempo de execução:

from azure_functions_agents import tool


@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
    return f"Created ticket for {title}: {summary}"

Para descrições de parâmetros mais detalhadas e validação, use um modelo Pydantic como esquema de ferramenta:

from pydantic import BaseModel, Field
from azure_functions_agents import tool


class LookupCustomerParams(BaseModel):
    customer_id: str = Field(description="Customer identifier from the CRM system.")


@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
    return f"Customer details for {params.customer_id}"

Também podes definir uma função Python simples sem o decorador. O runtime envolve a primeira função simples que encontra no ficheiro, usa o nome da função como nome da ferramenta e usa a docstring como descrição da ferramenta.

def summarize_order(order_id: str) -> str:
    """Summarize an order by order ID."""
    return f"Summary for order {order_id}"

Os nomes das ferramentas, as descrições, as anotações de tipo e as descrições dos campos do Pydantic ajudam o modelo a decidir quando e como invocar a ferramenta. Adiciona quaisquer dependências de pacotes usadas por ferramentas personalizadas ao requirements.txt, tal como farias com outro código de Python numa aplicação Funções do Azure.

Ferramentas de filtragem por agente

Os agentes herdam ferramentas personalizadas descobertas por defeito. Desabilite ou exclua ferramentas personalizadas num ficheiro de agente quando um agente específico não as deveria usar:

tools: false

tools:
  exclude:
    - submit_ticket

Configuração do fornecedor de modelo

O runtime utiliza o Microsoft Agent Framework para chamar fornecedores de modelos. O suporte de pré-visualização inclui Azure OpenAI, Azure AI Foundry e OpenAI.

Seleção do fornecedor

Deve configurar pelo menos um sinal de fornecedor para o tempo de execução para criar um cliente de chat. Podes definir explicitamente o fornecedor usando a AZURE_FUNCTIONS_AGENTS_PROVIDER definição ou deixar que o tempo de execução infira o fornecedor a partir das outras definições da tua aplicação.

Use estas definições de fornecedores:

Quando não defines AZURE_FUNCTIONS_AGENTS_PROVIDER, o tempo de execução deteta automaticamente o fornecedor nesta ordem:

1. AZURE_OPENAI_ENDPOINTseleciona Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINTseleciona Azure AI Foundry.
3. OPENAI_API_KEY seleciona OpenAI.

Quando se recorre à deteção automática, a definição específica do fornecedor que identificou o prestador ainda precisa de ser acompanhada pela definição do modelo exigida pelo prestador. Por exemplo, FOUNDRY_PROJECT_ENDPOINT ainda precisa FOUNDRY_MODELde , e AZURE_OPENAI_ENDPOINT ainda precisa AZURE_OPENAI_DEPLOYMENTde .

AZURE_FUNCTIONS_AGENTS_MODEL é uma configuração de modelo de reserva em tempo de execução. Os seus valores válidos dependem do fornecedor ativo:

• Para o Azure AI Foundry, use um nome de implementação de modelo que exista no projeto Foundry, como gpt-5.4.
• Para o Azure OpenAI, use o nome de implementação apenas se quiser intencionalmente o plano B para todo o tempo de execução. Na maioria das aplicações, define AZURE_OPENAI_DEPLOYMENT em vez disso.
• Para OpenAI, use o nome do modelo aceite pela API OpenAI, como gpt-4o-mini.

Precedência do modelo

A seleção do modelo utiliza esta precedência geral:

1. O modelo solicitado pelo agente ou pela chamada em tempo de execução.
2. Definições específicas do fornecedor, como AZURE_OPENAI_DEPLOYMENT ou FOUNDRY_MODEL.
3. O modelo definiu em AZURE_FUNCTIONS_AGENTS_MODEL.
4. O modelo padrão incorporado do fornecedor ativo.

Configuração de identidade gerida

O runtime utiliza identidades geridas ao ligar-se a recursos do Azure que suportam autenticação Microsoft Entra. Use AZURE_CLIENT_ID como seletor de identidade predefinido da aplicação, ou use definições específicas de funcionalidades para um controlo mais preciso:

1. Quando não há configuração de identidade, o runtime usa o DefaultAzureCredential, que resolve para a identidade gerida atribuída pelo sistema no Azure e para a identidade do seu programador (CLI do Azure ou Visual Studio) localmente.
2. Quando uma chave API é configurada no Azure OpenAI (usando AZURE_OPENAI_API_KEY), o fornecedor do modelo usa a chave em vez de uma identidade gerida. Para mais informações, consulte a extensão Azure OpenAI para Funções do Azure.
3. O histórico de sessões utiliza a mesma configuração padrão de identidade de armazenamento do host que o host do Funções do Azure. Use AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri, e AzureWebJobsStorage__clientId para configurar armazenamento baseado em identidade para o histórico apoiado em blobs. O runtime não utiliza uma definição de identidade específica para o agente para o histórico da sessão. Para mais informações, consulte Definir ligações no guia para programadores de Funções.

Pontos finais incorporados

O runtime expõe endpoints incorporados opcionais quando um agente opta por aderir através das builtin_endpoints definições no seu material inicial. Estes endpoints são úteis para desenvolvimento, testes e diagnóstico. Não são concebidos como a interface principal da aplicação de produção.

Ativar endpoints incorporados na matéria frontal do agente:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

As definições debug_chat_ui: true também ativam as chat APIs e chatstream porque a interface depende delas. Define chat_api: true sozinho quando quiseres acesso ao chat programático sem a interface de depuração.

Rotas de terminais

O segmento <AGENT_NAME> de rota vem do nome do .agent.md ficheiro, não do campo de visualização name . Por exemplo, main.agent.md usa /agents/main/.

Recuperação de chaves

Quando hospedas a interface de chat no Azure, ele solicita uma tecla de função antes de enviar mensagens. Podes usar a chave ao ligar diretamente às APIs de chat HTTP.

Use o seguinte az functionapp keys list comando para recuperar a tecla de função padrão da sua aplicação:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "functionKeys.default" \
  --output tsv

Neste exemplo, substitua <RESOURCE_GROUP> e <FUNCTION_APP_NAME> pelos nomes do seu grupo e da aplicação. Pode incluir a chave devolvida no x-functions-key cabeçalho ou um code parâmetro de string de consulta no pedido HTTP ao endpoint.

Ao ligar-se a um cliente MCP, peça antes o sistema de extensão MCP usando o seguinte comando:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "systemKeys.mcp_extension" \
  --output tsv

O endpoint MCP requer esta chave do sistema.

Fluxo de pedidos da API de chat

Ambas as APIs de chat incorporadas esperam um corpo JSON com um prompt campo:

{
  "prompt": "Summarize today's failures."
}

Usa POST /agents/<AGENT_NAME>/chat quando quiseres uma resposta JSON. O corpo de resposta inclui session_id, response, e tool_calls. O runtime também reflete o mesmo ID de sessão no x-ms-session-id cabeçalho de resposta.

Usa POST /agents/<AGENT_NAME>/chatstream quando quiseres Server-Sent Eventos (SSE). O fluxo começa com um session evento que contém o ID da sessão resolvido, seguido de zero ou mais delta, intermediate, tool_start, e tool_end eventos, e termina com ou doneerror.

Para continuar uma conversa multiturno, envie o ID da sessão da resposta anterior no x-ms-session-id cabeçalho do pedido em chamadas posteriores chat ou chatstream ou. Se omitires esse cabeçalho, o runtime cria automaticamente uma nova sessão.

POST /agents/main/chatstream HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
x-ms-session-id: <SESSION_ID_FROM_A_PREVIOUS_RESPONSE>

{"prompt":"Continue the last summary and add blockers."}

Sessões e estado

As interações entre agentes em múltiplos turnos requerem histórico de sessão. O tempo de execução gere automaticamente o armazenamento da sessão com base no ambiente:

O tempo de execução não requer uma base de dados separada para a sessão. A execução sandboxed também é consciente da sessão: quando não existe um ID de sessão explícito disponível, o runtime usa uma sessão sandbox isolada e nova para que invocações não relacionadas não partilhem estado.

Planos de alojamento suportados

O runtime dos agentes serverless suporta estes planos de alojamento Funções do Azure:

Ambos os planos suportam identidade gerida, integração com redes virtuais e Application Insights.

Conteúdo relacionado

• Ambiente de execução de agentes serverless no Funções do Azure
• Constrói agentes serverless usando Funções do Azure
• Compare o tempo de execução dos agentes serverless com outras opções de agentes Microsoft
• Alojamento do plano Flex Consumption