Referência de runtime de agentes serverless

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

Importante

O runtime do agente serverless está atualmente em pré-visualização. Recursos, nomes de configuração e conectores com suporte podem ser alterados antes da disponibilidade geral.

Referência de ficheiro do agente

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

Campos front-matéria

Use estes campos de front matter para configurar um agente:

Campo	Obrigatório	Descrição
name	Yes	Nome de exibição do agente.
description	Yes	Breve descrição do que o agente faz e quando ele deve ser usado.
trigger	Sim (a menos que builtin_endpoints esteja ativado)	Define como o agente é invocado. Somente um gatilho é permitido por arquivo de agente.
builtin_endpoints	No	Habilita pontos de extremidade integrados de depuração e composição. Use true para habilitar todos os endpoints integrados ou para configurar debug_chat_ui, chat_api e mcp individualmente. debug_chat_ui: truetambém permite as chat de backup chatstream e endpoint porque a interface embutida chama essas APIs.
input_schema	No	JSON Schema usado para validar corpos de requisições HTTP para agentes acionados por HTTP.
logger	No	Controla se o log de runtime está habilitado para o agente. Usa true como padrão.
mcp	No	Controla o acesso a servidores MCP descobertos por mcp.json. Use false para desabilitar servidores MCP para esse agente ou para exclude remover servidores específicos.
metadata	No	Metadados personalizados para sua própria organização ou ferramentas.
model	No	Substitui o modelo padrão configurado em agents.config.yaml ou nas configurações do aplicativo.
response_example	No	Formato de resposta de exemplo usado para orientar respostas estruturadas de agentes acionados por HTTP.
response_schema	No	Esquema JSON usado para validar respostas estruturadas retornadas por agentes disparados por HTTP.
skills	No	Controle o acesso às habilidades descobertas. Use false para desabilitar as habilidades deste agente ou exclude para remover habilidades específicas.
substitute_variables	No	Determina se a substituição de variáveis de ambiente é aplicada à matéria e instruções frontais. Usa true como padrão.
system_tools	No	Permite que um agente opte por não usar ferramentas de sistema configuradas, como execução sandbox.
timeout	No	Substitui o tempo limite de execução padrão, em segundos.
tools	No	Controle o acesso às ferramentas personalizadas de Python descobertas. Use false para desativar as ferramentas personalizadas deste agente ou use exclude para remover ferramentas específicas.

Configuração de gatilho

Cada arquivo agente suporta um gatilho, definido no trigger objeto na matéria inicial.

Campo	Obrigatório	Descrição
type	Yes	O tipo de bloqueio de gatilho. Veja a tabela de tipos suportados para valores permitidos.
args	Depende do tipo	Configurações específicas de gatilho que configuram qual evento inicia o agente.

Tipos de gatilho com suporte

A tabela a seguir lista os valores suportados trigger.type , seus requisitos argse links para a referência completa por tipo:

trigger.type	Obrigatório args	Referência
http_trigger	route	HTTP Trigger
timer_trigger	schedule	Gatilho do temporizador
queue_trigger	queue_name, connection	Gatilho de Fila
blob_trigger	path, connection	Gatilho de blob
event_grid_trigger	(nenhuma)	Gatilho da Grade de Eventos
event_hub_message_trigger	event_hub_name, connection	Gatilho do Hub de Eventos
service_bus_queue_trigger	queue_name, connection	Gatilho de fila do Barramento de Serviço
service_bus_topic_trigger	topic_name, subscription_name, connection	Gatilho de tópico do Barramento de Serviço
cosmos_db_trigger	connection, database_name, container_name	Gatilho do Azure Cosmos DB
cosmos_db_trigger_v3	database_name, collection_name, connection_string_setting	Gatilho do Cosmos DB v3
sql_trigger	table_name, connection_string_setting	Gatilho do SQL
mysql_trigger	table_name, connection_string_setting	Gatilho MySQL
kafka_trigger	topic, broker_list	Gatilho de Kafka
dapr_binding_trigger	binding_name	Gatilho de ligação Dapr
dapr_service_invocation_trigger	method_name	Gatilho de invocação de serviço Dapr
dapr_topic_trigger	pub_sub_name, topic	Gatilho de tópico Dapr
generic_trigger	type (nome do tipo de encadernação)	Gatilho genérico
connector_trigger	Configurado no namespace do conector.	Gatilho conector

Exemplos de gatilho

Os exemplos a seguir mostram configurações comuns de gatilhos:

Gatilho do temporizador (roda diariamente às 15h 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 de blob:

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

Configuração em todo o app (agents.config.yaml)

Use agents.config.yaml para as configurações padrão de tempo de execução do aplicativo inteiro que todos os agentes podem herdar. O runtime pode carregar um aplicativo sem esse arquivo. Adicione isso quando precisar de configurações compartilhadas, como a implantação de um modelo, o tempo limite ou o endpoint de execução em sandbox.

Esse arquivo é uma entrada no nível do aplicativo. O ambiente de execução também descobre servidores MCP em mcp.json, habilidades em skills/ e ferramentas personalizadas em Python em tools/. Esses recursos são habilitados em agentes por padrão. Os metadados iniciais do agente podem substituir as configurações padrão de runtime ou filtrar servidores, habilidades e ferramentas do MCP herdados.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Agentes individuais podem sobrescrever as configurações de tempo de execução compatíveis no próprio front matter.

Campos de configuração

Use estes campos de nível superior em agents.config.yaml:

Campo	Obrigatório	Descrição
model	No	Modelo padrão ou implantação de modelo usados por agentes que não definem model em seu próprio front matter.
timeout	No	Tempo limite de execução padrão, em segundos. O padrão de runtime é de 900 segundos.
system_tools.dynamic_sessions_code_interpreter.endpoint	Ao usar a execução em área restrita	Ponto de extremidade de gerenciamento para o pool dinâmico de sessões dos Aplicativos de Contêiner do Azure usados pelas ferramentas de sandbox.
system_tools.dynamic_sessions_code_interpreter.client_id	No	ID do cliente da identidade gerenciada usada para chamar o pool de sessão.
tools.exclude	No	Lista de exclusões globais para ferramentas de Python personalizadas descobertas da pasta tools/.

Ordem de resolução

O runtime resolve os valores primeiro a partir do front matter do agente, depois de agents.config.yaml e, em seguida, das configurações do aplicativo e dos padrões do runtime. Os valores de cadeia de caracteres agents.config.yaml podem fazer referência a configurações do aplicativo, como $AZURE_OPENAI_DEPLOYMENT ou $ACA_SESSION_POOL_ENDPOINT.

Mantenha os padrões de modelo, tempo limite e ferramenta do sistema em agents.config.yaml. Mantenha as definições de servidores MCP remotos, incluindo endpoints de servidores MCP de namespaces de conectores, em mcp.json.

Substituição de variável

O ambiente de execução pode substituir configurações do aplicativo e variáveis de ambiente em valores de string na seção inicial do agente, no corpo das instruções do agente, em agents.config.yaml e mcp.json.

Para substituições, você pode usar ou $SETTING_NAME%SETTING_NAME%, que são tratados da mesma forma pelo tempo de execução. Os nomes de variáveis devem começar com 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 string, incluindo strings aninhadas em objetos ou listas. Não se aplica a teclas objeto.
• Blocos de código delimitados no corpo das instruções do agente não são substituídos, portanto 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 ausentes permanecem inalteradas. Valores vazios resolvem para cadeias vazias.
• Substituição é uma passagem única. A sintaxe ${SETTING_NAME} não é compatível.
• Para desabilitar a substituição por um agente, defina substitute_variables: false no arquivo agente. Isso não desativa a substituição em agents.config.yaml ou mcp.json.

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

Quando um aplicativo usa servidores MCP remotos, adicione mcp.json à raiz do projeto do aplicativo de funções. O ambiente de execução descobre, neste arquivo, servidores HTTP remotos ou servidores MCP HTTP com suporte a streaming e disponibiliza suas ferramentas aos agentes, sujeito a quaisquer filtros específicos por agente.

Campos de entrada do servidor

Use estes campos em cada servers entrada:

Campo	Obrigatório	Descrição
type	Yes	Use http ou streamable-http. Os servidores MCP locais stdio não são compatíveis com o runtime.
url	Yes	Endpoint remoto do servidor MCP. Há suporte para substituição de variável de ambiente.
headers	No	Cabeçalhos estáticos para um servidor MCP remoto genérico. Não armazene segredos estáticos em mcp.json.
auth.scope	Ao usar a autenticação Microsoft Entra	Escopo de token do Microsoft Entra usado para autenticar chamadas ao servidor MCP.
auth.client_id	No	ID do cliente da identidade gerenciada a ser usada ao autenticar com esse servidor MCP. Omita esse campo para usar a identidade gerenciada atribuída pelo sistema do aplicativo de funções no Azure.

Autenticação

Use o escopo do Azure API Hub quando o agente consome um servidor MCP gerenciado do namespace de um conector. Não armazene segredos do usuário 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 configuração auth.client_id seleciona qual identidade gerenciada é usada para se autenticar no servidor MCP. Defina-o como a ID do cliente de uma identidade gerenciada atribuída pelo usuário. Omita isso para usar a identidade gerenciada atribuída pelo sistema do aplicativo de função no Azure. A identidade selecionada, ou sua identidade de desenvolvedor local, quando você executa localmente, deve ter permissão para chamar o servidor MCP.

Conectores do Azure

Os conectores permitem que os agentes trabalhem com serviços externos sem código de cliente de API personalizada. Por exemplo, um conector Microsoft 365 Outlook pode enviar email, um conector do Teams pode trabalhar com mensagens e outros conectores podem chamar ações em sistemas como Salesforce, SAP ou SQL. Um Namespace do Conector hospeda as conexões, os gatilhos e os servidores MCP que disponibilizam essas integrações ao seu aplicativo.

Para usar recursos de conectores em um aplicativo de agentes sem servidor, primeiro crie um recurso de namespace de conectores, crie uma conexão com o serviço e autorize essa conexão. Em seguida, escolha como o agente usa a conexão:

• Os gatilhos de conector iniciam agentes quando algo acontece em um serviço conectado, como um novo e-mail, uma mensagem do Teams ou um evento do calendário. Para usar um, crie um gatilho no Namespace do Conector que usa a conexão autorizada e configure o agente com o nome do gatilho e os argumentos dessa definição de gatilho do conector.
• As ferramentas MCP do Connector permitem que os agentes executem ações de serviço, como enviar e-mail ou atualizar um registro. Para usá-los, crie um servidor MCP no Namespace do Conector que usa a conexão autorizada e adicione o ponto de extremidade do servidor MCP a mcp.json.

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

Habilidades

Armazene recursos de prompt reutilizáveis em skills/. Eles ajudam a manter as instruções do agente base pequenas ao disponibilizar instruções específicas do domínio quando necessário. O runtime usa o formato habilidades do agente .

Formato de habilidade

O runtime escaneia skills/ na raiz do projeto do app de função e descobre recursivamente pastas que contêm SKILL.md.

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

O arquivo SKILL.md contém um cabeçalho YAML seguido 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 seus arquivos de agentes e outros recursos do projeto:

• Cada pasta de habilidade deve conter um arquivo SKILL.md.
• Os campos name e description são obrigatórios.
• Use letras minúsculas, números e hífens simples para nomes de habilidades. Não use espaços, sublinhados, letras maiúsculas, hifens à esquerda, hifens à direita ou hifens repetidos.
• Os nomes de habilidades devem ser exclusivos em todo o aplicativo.
• A descrição deve explicar o que a habilidade faz e quando o agente deve usá-la. O runtime carrega nomes de habilidades e descrições primeiro para que o agente possa decidir quando carregar a habilidade completa.
• As habilidades podem incluir vários arquivos de markdown na mesma pasta de habilidades. Faça referência aos arquivos Markdown de suporte de SKILL.md usando links relativos.
• O ambiente de execução de agentes serverless oferece suporte apenas a arquivos Markdown como conteúdo de skills. Se uma habilidade precisar de comportamento executável, empacote esse código como uma ferramenta Python personalizada e refira-se à ferramenta pelo nome das instruções de habilidade.

Habilidades de filtragem por agente

Os agentes herdam todas as habilidades descobertas por padrão. Desabilite ou exclua habilidades em um arquivo de agente quando um agente específico não deve usá-las:

skills: false

skills:
  exclude:
    - incident-response

Execução em área restrita

Para execução de código ou automação do navegador, o runtime pode usar sessões dinâmicas do Aplicativos de Contêiner do Azure. As sessões dinâmicas fornecem ambientes isolados a partir de conjuntos de sessões. O runtime usa sessões de interpretador de código para fornecer uma execute_python ferramenta aos agentes.

Configuration

Configurar a execução em área restrita em agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

• O pool deve ser um pool de sessões de interpretador de código em Python, como um criado com --container-type PythonLTS.
• O valor de endpoint é o endpoint de gerenciamento do pool de sessões.
• No Azure, a identidade gerenciada usada pelo aplicativo 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 interpretador de código do Aplicativos de Contêiner do Azure exigem as funções Azure ContainerApps Session Executor e Contributor no conjunto de sessões.
• Ao executar localmente, a identidade do desenvolvedor deve ter o mesmo acesso necessário ao pool de sessões.
• Para usar uma identidade gerenciada atribuída pelo usuário para execução em área restrita, defina system_tools.dynamic_sessions_code_interpreter.client_id como a ID do cliente da identidade que tem as atribuições de função necessárias. Se essa configuração não estiver configurada, o runtime usará AZURE_CLIENT_ID e depois a cadeia de credenciais padrão.

A ferramenta de sandbox executa Python em uma sessão isolada. Variáveis, importações e arquivos podem persistir entre chamadas de ferramenta na mesma sessão do agente. Quando nenhuma ID de sessão do agente está disponível, o runtime usa uma nova sessão de área restrita para que execuções não relacionadas não compartilhem o estado.

Desabilitando por agente

Os agentes herdam a execução em área restrita quando ela é configurada globalmente. Você pode desativar a execução para um agente específico definindo dynamic_sessions_code_interpreter como false no arquivo do agente.

system_tools:
  dynamic_sessions_code_interpreter: false

Ferramentas de Python personalizadas

Use ferramentas Python personalizadas quando precisar de lógica específica para o app que as capacidades integradas do runtime não cobrem. Ferramentas personalizadas rodam no processo do app de funções, não em uma sessão sandbox.

Descoberta de ferramentas

Adicione arquivos de ferramenta à tools/ pasta na raiz do projeto do aplicativo de funções:

tools/
  submit_ticket.py
  lookup_customer.py

O runtime descobre arquivos cujos .pytools/ nomes de arquivo não começam com _. Na prévia atual, o runtime registra a primeira ferramenta compatível em cada arquivo. Use uma ferramenta por arquivo para manter a descoberta previsível.

Definindo ferramentas

Defina uma ferramenta usando o decorador @tool do pacote runtime:

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 avançadas e validação, use um modelo Pydantic como o esquema de ferramentas:

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

Você também pode definir uma função Python sem o decorador. O runtime encapsula a primeira função simples encontrada no arquivo, usa o nome da função como o nome da ferramenta e usa o docstring como a descrição da ferramenta.

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

Nomes de ferramentas, descrições, indicações de tipo e descrições de campos do Pydantic ajudam o modelo a decidir quando e como chamar a ferramenta. Adicione a requirements.txt quaisquer dependências de pacotes usadas por ferramentas personalizadas, da mesma forma que faria com outro código Python em um aplicativo do Azure Functions.

Ferramentas de filtragem por agente

Os agentes herdam as ferramentas personalizadas descobertas por padrão. Desabilite ou exclua ferramentas personalizadas em um arquivo de agente quando um agente específico não deve usá-las:

tools: false

tools:
  exclude:
    - submit_ticket

Configuração do provedor de modelo

O runtime usa Microsoft Agent Framework para chamar provedores de modelo. O suporte para a versão prévia inclui Azure OpenAI, Fábrica de IA do Azure e OpenAI.

Seleção do provedor

Você deve configurar pelo menos um sinal de provedor para o runtime para criar um cliente de chat. Você pode definir explicitamente o provedor usando a AZURE_FUNCTIONS_AGENTS_PROVIDER configuração ou deixar o tempo de execução inferir o provedor a partir das outras configurações do seu aplicativo.

Use estas configurações de provedores:

Fornecedor	AZURE_FUNCTIONS_AGENTS_PROVIDER valor	Configurações necessárias	Configurações opcionais	Comportamento de configuração de modelos
Fábrica de IA do Azure	foundry	FOUNDRY_PROJECT_ENDPOINT	AZURE_CLIENT_ID Quando você quer uma identidade gerenciada atribuída ao usuário	Defina FOUNDRY_MODEL para o nome de implantação do modelo que o projeto Foundry deve usar.
OpenAI do Azure	azure_openai	AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT	AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_VERSION, AZURE_CLIENT_ID quando você quer uma identidade gerenciada atribuída pelo usuário	Defina AZURE_OPENAI_DEPLOYMENT para o nome de implantação do Azure OpenAI.
OpenAI	openai	OPENAI_API_KEY	None	Defina AZURE_FUNCTIONS_AGENTS_MODEL para o nome do modelo OpenAI quando você não passa um modelo em configuração de agente ou runtime.

Quando você não define AZURE_FUNCTIONS_AGENTS_PROVIDER, o tempo de execução detecta automaticamente o provedor nesta ordem:

1. AZURE_OPENAI_ENDPOINTseleciona Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINTseleciona Fábrica de IA do Azure.
3. OPENAI_API_KEY seleciona OpenAI.

Quando você depende da detecção automática, a configuração específica do provedor que identificou o provedor ainda precisa ser acompanhada pela configuração de modelo exigida pelo provedor. 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 recurso, que abrange toda a execução. Seus valores válidos dependem do provedor ativo:

• Para Fábrica de IA do Azure, use um nome de implantação de modelo que exista no projeto Foundry, como gpt-5.4.
• Para o Azure OpenAI, use o nome da implantação apenas se você quiser intencionalmente o recurso de rechange em tempo de execução. Na maioria dos apps, configure AZURE_OPENAI_DEPLOYMENT em vez disso.
• Para OpenAI, use o nome do modelo aceito pela API da OpenAI, como gpt-4o-mini.

Precedência do modelo

A seleção de modelo usa essa precedência geral:

1. O modelo solicitado pelo agente ou por uma chamada em tempo de execução.
2. Configurações específicas do provedor, como AZURE_OPENAI_DEPLOYMENT ou FOUNDRY_MODEL.
3. O modelo definiu em AZURE_FUNCTIONS_AGENTS_MODEL.
4. O modelo padrão embutido do provedor ativo.

Configuração de identidade gerenciada

O runtime utiliza identidades gerenciadas ao se conectar a recursos do Azure que suportam autenticação Microsoft Entra. Use AZURE_CLIENT_ID como seletor de identidade padrão do app, ou use configurações específicas de recursos para um controle mais específico:

Recurso de tempo de execução	Configuração de identidade	Reserva1
Azure OpenAI modelprovider 2	AZURE_CLIENT_ID	DefaultAzureCredential
provedor de modelos do Fábrica de IA do Azure	AZURE_CLIENT_ID	DefaultAzureCredential
Aplicativos de Contêiner do Azure área restrita de sessões dinâmicas	system_tools.dynamic_sessions_code_interpreter.client_id	AZURE_CLIENT_ID, então DefaultAzureCredential
Servidores MCP hospedados em espaços de nomes de conectores	O valor auth.client_id na entrada de servidor em mcp.json	AZURE_CLIENT_ID, então DefaultAzureCredential
Histórico de sessões com respaldo deblobs 3	AzureWebJobsStorage__clientId	AZURE_CLIENT_ID, então DefaultAzureCredential

1. Quando nenhuma configuração de identidade está configurada, o runtime usa o DefaultAzureCredential, que resolve para a identidade gerenciada atribuída pelo sistema no Azure e para a identidade do seu desenvolvedor (CLI do Azure ou Visual Studio) localmente.
2. Quando uma chave de API é configurada no Azure OpenAI (usando AZURE_OPENAI_API_KEY), o provedor do modelo usa a chave em vez de uma identidade gerenciada. Para mais informações, veja a extensão Azure OpenAI para Azure Functions.
3. O histórico de sessão usa a mesma configuração padrão de identidade de armazenamento do host do Azure Functions. Use AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri e AzureWebJobsStorage__clientId para configurar o armazenamento baseado em identidade para o histórico com suporte de blob. O runtime não usa uma configuração de identidade específica do agente separada para o histórico de sessão. Para mais informações, veja Definir conexões no guia para desenvolvedores de Funções.

Pontos de extremidade internos

O runtime expõe endpoints opcionais embutidos quando um agente opta por usar as builtin_endpoints configurações em seu material inicial. Esses endpoints são úteis para desenvolvimento, testes e diagnósticos. Eles não foram projetados como a interface principal de aplicação de produção.

Ative endpoints integrados na matéria frontal do agente:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

A configuração debug_chat_ui: true também ativa as chat APIs e chatstream porque a interface depende delas. Configurado chat_api: true sozinho quando você quiser acesso ao chat programático sem a interface de depuração.

Rotas de endpoint

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

Superfície	Rota	Requisito de chave
Interface do usuário do chat	/agents/<AGENT_NAME>/	Tecla de função (solicitada no navegador).
HTTP chat API	POST /agents/<AGENT_NAME>/chat	Chave de função.
Streaming chat API	POST /agents/<AGENT_NAME>/chatstream	Chave de função.
Ponto de extremidade MCP	/runtime/webhooks/mcp	mcp_extension chave do sistema.

Recuperando chaves

Quando você hospeda a interface de chat no Azure, ele solicita uma tecla de função antes de enviar mensagens. Você pode usar a chave ao chamar diretamente as APIs de chat HTTP.

Use o seguinte az functionapp keys list comando para recuperar a tecla de função padrão do seu app:

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 do aplicativo. Você pode incluir a chave retornada no x-functions-key cabeçalho ou um code parâmetro de string de consulta na requisição HTTP para o endpoint.

Ao se conectar a um cliente MCP, solicite 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 essa chave do sistema.

Fluxo de requisições da API do chat

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

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

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

Use POST /agents/<AGENT_NAME>/chatstream quando quiser Server-Sent Eventos (SSE). O fluxo começa com um session evento que contém o ID da sessão resolvido, seguido por 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 da solicitação em chamadas posteriores ou ou (later chat or chatstream calls). Se você omitir esse cabeçalho, o tempo de execução cria uma nova sessão automaticamente.

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

Interações com agentes em múltiplos turnos exigem histórico de sessão. O runtime gerencia automaticamente o armazenamento da sessão com base no ambiente:

Environment	Armazenamento	Configuration
Azure	Armazenamento de Blobs na conta padrão de armazenamento do host (AzureWebJobsStorage)	Cadeia de conexão ou baseada em identidade (preferido). Veja Configuração de identidade gerenciada.
Desenvolvimento local	Baseado em arquivos no diretório de configuração dos agentes locais	Não precisa de configuração.

O runtime não exige um banco de dados separado para a sessão. A execução sandboxed também é consciente da sessão: quando não há um ID explícito de sessão disponível, o runtime usa uma sessão sandbox isolada nova para que invocações não relacionadas não compartilhem estado.

Planos de hospedagem suportados

O runtime dos agentes serverless suporta estes planos de hospedagem do Azure Functions:

Plano	Escalabilidade serverless	Notes
Consumo flexível	Yes	Escala até zero, faturamento por segundo e escalonamento automático. Recomendado para a maioria das cargas de trabalho dos agentes.
Dedicado (Serviço de Aplicativo)	No	Instâncias sempre ativas com escalonamento manual ou baseado em regras. Use quando você já tiver instâncias de plano de App Service com capacidade disponível.

Ambos os planos suportam identidade gerenciada, integração com redes virtuais e Insights de Aplicação.

Conteúdo relacionado

• Runtime de agentes sem servidor no Azure Functions
• Crie agentes sem servidor usando o Azure Functions
• Compare o runtime dos agentes serverless com outras opções de agentes da Microsoft
• Hospedagem do plano Flex Consumption