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.

Importante

O tempo de execução do agente serverless está atualmente em pré-visualização. Funcionalidades, nomes de configuração e conectores suportados podem mudar antes da disponibilidade geral.

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:

Campo	Required	Description
name	Sim	Nome de exibição para o agente.
description	Sim	Breve descrição do que o agente faz e quando deve ser utilizado.
trigger	Sim (a menos que builtin_endpoints esteja ativado)	Define como o agente é invocado. Só é permitido um disparador por ficheiro de agente.
builtin_endpoints	No	Ativa pontos finais de depuração e composição integrados. Use true para ativar todos os endpoints incorporados, ou configurar debug_chat_ui, chat_api, e mcp individualmente. debug_chat_ui: truetambém permite as chat de backing chatstream e endpoint porque a interface integrada chama essas APIs.
input_schema	No	Esquema JSON usado para validar corpos de pedidos HTTP para agentes ativados por HTTP.
logger	No	Controla se o registo em tempo de execução está ativado para o agente. O valor padrão é true.
mcp	No	Controla o acesso a servidores MCP descobertos a partir de mcp.json. Use false para desativar os servidores MCP para este agente, ou use exclude para remover servidores específicos.
metadata	No	Metadados personalizados para a sua organização ou para o seu conjunto de ferramentas.
model	No	Substitui o modelo predefinido configurado em agents.config.yaml ou nas definições da aplicação.
response_example	No	Exemplo de forma de resposta usada para guiar respostas estruturadas de agentes desencadeados por HTTP.
response_schema	No	Esquema JSON usado para validar respostas estruturadas devolvidas por agentes ativados por HTTP.
skills	No	Controla o acesso às competências descobertas. Use false para desativar habilidades deste agente, ou para exclude remover habilidades específicas.
substitute_variables	No	Controla se a substituição de variáveis ambientais é aplicada à matéria inicial e às instruções. O valor padrão é true.
system_tools	No	Permite a um agente optar por não participar em ferramentas de sistema configuradas, como execuções em sandbox.
timeout	No	Anula o tempo de execução padrão, em segundos.
tools	No	Controla o acesso a ferramentas Python personalizadas descobertas. Use false para desativar as ferramentas personalizadas deste agente, ou use exclude para remover ferramentas específicas.

Configuração do acionador

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

Campo	Required	Description
type	Sim	O tipo de bloqueio do gatilho. Consulte a tabela de tipos suportados para valores permitidos.
args	Depende do tipo	Definições específicas do trigger que definem qual evento inicia o agente.

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:

trigger.type	Obrigatório args	Reference
http_trigger	route	Gatilho HTTP
timer_trigger	schedule	Gatilho do temporizador
queue_trigger	queue_name, connection	Gatilho de fila
blob_trigger	path, connection	Gatilho de blob
event_grid_trigger	(nenhum)	Acionador do Event Grid
event_hub_message_trigger	event_hub_name, connection	Gatilho do Event Hub
service_bus_queue_trigger	queue_name, connection	Gatilho da fila do Service Bus
service_bus_topic_trigger	topic_name, subscription_name, connection	Gatilho do tópico do Service Bus
cosmos_db_trigger	connection, database_name, container_name	Gatilho do 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	Trigger 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 tópico Dapr
generic_trigger	type (nome do tipo de ligação)	Gatilho genérico
connector_trigger	Configurado no espaço de nomes do Conector.	Gatilho de ligação

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:

Campo	Required	Description
model	No	O modelo predefinido ou a implementação do modelo utilizada por agentes que não definem model nos seus próprios metadados iniciais.
timeout	No	Tempo de execução padrão, em segundos. O tempo de execução padrão é de 900 segundos.
system_tools.dynamic_sessions_code_interpreter.endpoint	Ao usar execução em sandbox	Endpoint de gestão para o pool de sessões dinâmicas do Azure Container Apps utilizado pelas ferramentas de sandbox.
system_tools.dynamic_sessions_code_interpreter.client_id	No	ID de cliente da identidade gerida usada para invocar o conjunto de sessões.
tools.exclude	No	Lista global de exclusão para ferramentas de Python personalizadas descobertas na pasta tools/.

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:

Campo	Required	Description
type	Sim	Utilizar http ou streamable-http. Servidores MCP locais stdio não são suportados pelo runtime.
url	Sim	Ponto terminal remoto do servidor MCP. A substituição de variáveis de ambiente é suportada.
headers	No	Cabeçalhos estáticos para um servidor MCP remoto genérico. Não guarde segredos estáticos em mcp.json.
auth.scope	Ao usar autenticação Microsoft Entra	Escopo do token Microsoft Entra usado para autenticar chamadas para o servidor MCP.
auth.client_id	No	ID de cliente da identidade gerida a usar ao autenticar-se neste servidor MCP. Omita este campo para usar a identidade gerida atribuída pelo sistema da aplicação de funções no Azure.

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:

Provider	AZURE_FUNCTIONS_AGENTS_PROVIDER valor	Configurações necessárias	Configurações opcionais	Comportamento da definição de modelos
Azure AI Foundry	foundry	FOUNDRY_PROJECT_ENDPOINT	AZURE_CLIENT_ID Quando queres uma identidade gerida atribuída pelo utilizador	Definir FOUNDRY_MODEL para o nome de implementação do modelo que o projeto Foundry deve usar.
Azure OpenAI	azure_openai	AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT	AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_VERSION, AZURE_CLIENT_ID quando pretende uma identidade gerida atribuída pelo utilizador	Definir AZURE_OPENAI_DEPLOYMENT para o nome de implementação Azure OpenAI.
OpenAI	openai	OPENAI_API_KEY	None	Define AZURE_FUNCTIONS_AGENTS_MODEL para o nome do modelo OpenAI quando não passares um modelo em configuração de agente ou runtime.

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:

Funcionalidade de execução	Configuração de identidade	Plano B1
Azure OpenAI modelprovider 2	AZURE_CLIENT_ID	DefaultAzureCredential
fornecedor de modelos do Azure AI Foundry	AZURE_CLIENT_ID	DefaultAzureCredential
Sandbox de sessões dinâmicas do Azure Container Apps	system_tools.dynamic_sessions_code_interpreter.client_id	AZURE_CLIENT_ID, então DefaultAzureCredential
Servidores MCP alojados 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 apoiado porblobs 3	AzureWebJobsStorage__clientId	AZURE_CLIENT_ID, então DefaultAzureCredential

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

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

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:

Environment	Armazenamento	Configuration
Azure	Armazenamento de Blobs na conta de armazenamento padrão do host (AzureWebJobsStorage)	Cadeia de ligação ou baseada em identidade (preferido). Ver Configuração de identidade gerida.
Desenvolvimento local	Baseado em ficheiros no diretório de configuração dos agentes locais	Não é necessária configuração.

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:

Plano	Escalabilidade serverless	Notes
Consumo Flexível	Sim	Escala até zero, faturação 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 escalabilidade manual ou baseada em regras. Usa quando já tiveres instâncias de plano de App Service com capacidade disponível.

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