Ambiente de execução de agentes sem servidor no Azure Functions

O runtime de agentes sem servidor do Azure Functions é um modelo de programação centrado em Markdown para criar agentes de IA como aplicativos do Azure Functions. Em vez de unir hospedagem, gatilhos, clientes de modelo, ferramentas, armazenamento de sessão, identidade e observabilidade, você define agentes em .agent.md arquivos e os implanta como um aplicativo de funções.

O ambiente de execução foi projetado para agentes que reagem a eventos, usam ferramentas e são executados em infraestrutura serverless. Os agentes podem ser acionados por solicitações HTTP, agendamentos, filas, mensagens, alterações em bancos de dados e outros eventos; usar servidores MCP remotos, servidores MCP hospedados em namespaces de conectores, habilidades reutilizáveis e execução em sandbox; e ser executados com os mesmos recursos de implantação, identidade, monitoramento e escala usados por outros aplicativos do Azure Functions. Para lógica específica do aplicativo, você pode escrever ferramentas personalizadas no mesmo aplicativo de funções.

Note

O runtime de agentes sem servidor está em versão prévia. Recursos, nomes de configuração e conectores com suporte podem ser alterados antes da disponibilidade geral.

Por que criar agentes em Azure Functions?

Os agentes de produção precisam de mais do que um prompt e um modelo. Eles precisam de maneiras confiáveis para iniciar o trabalho, chamar sistemas externos, persistir o histórico de conversas, executar código não confiável com segurança, autenticar sem segredos, emitir telemetria e dimensionar sob demanda.

Azure Functions já fornece um modelo de computação controlado por eventos para essas preocupações operacionais. O runtime de agentes sem servidor aplica esse modelo aos agentes:

  • Os agentes são a unidade de trabalho. Um .agent.md arquivo define o gatilho e as instruções para um agente.
  • Os eventos iniciam agentes. Os gatilhos de Funções permitem que os agentes executem tarefas de forma agendada, reajam a filas e eventos ou exponham pontos de extremidade HTTP.
  • Os recursos são configurados primeiro, com código quando você precisa dele. Os agentes podem usar, na configuração, servidores MCP remotos, servidores MCP hospedados em namespaces de conector, habilidades e execução de código em área restrita. Use ferramentas personalizadas para lógica específica do aplicativo.
  • A hospedagem não tem servidor. O Consumo Flex oferece suporte a escalonamento até zero, cobrança por segundo, identidade gerenciada, integração com rede virtual e Application Insights.
  • O encanamento operacional é interno. O runtime cuida da descoberta de agentes, do registro de gatilhos, da montagem de ferramentas, do histórico da sessão e de endpoints integrados opcionais.

Anatomia do projeto

Um aplicativo de agentes sem servidor é um aplicativo Python Azure Functions com arquivos específicos do agente ao lado dos arquivos de projeto normais do Functions.

Arquivo ou pasta Obrigatório Purpose
function_app.py Yes Importa create_function_app() e retorna o aplicativo de Azure Functions configurado.
*.agent.md Yes Define os agentes. O bloco de metadados YAML configura o agente, e o corpo em Markdown se transforma nas instruções.
agents.config.yaml No Define padrões de runtime em todo o aplicativo, como configurações de modelo, tempo limite e área restrita.
mcp.json Ao usar servidores MCP ou ferramentas conectoras Define servidores HTTP MCP remotos que os agentes podem usar como ferramentas, incluindo ferramentas de conector para tarefas como enviar email ou trabalhar com o Teams.
tools/ No Contém ferramentas de Python personalizadas para recursos que não são cobertos por servidores MCP, conexões, habilidades ou execução em área restrita.
skills/ No Contém recursos de prompt reutilizáveis SKILL.md que os agentes podem carregar conforme necessário.
host.json Yes Configura o host do Azure Functions.
requirements.txt Yes Inclui o pacote de runtime de agentes sem servidor e as dependências de Python específicas do aplicativo.
infra/ No Contém arquivos de infraestrutura como código usados por ferramentas de implantação, como azd.

Um projeto mínimo temfunction_app.py, host.jsonrequirements.txte pelo menos um .agent.md arquivo. Adicione agents.config.yaml quando o aplicativo precisar de padrões de runtime em todo o aplicativo.

Arquivos do agente

Um arquivo de agente usa um cabeçalho YAML seguido de instruções em Markdown. Este exemplo define um agente disparado pelo temporizador:

---
name: Daily Tech News Email
description: Fetches top tech news and emails a summary daily.

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

You are a news assistant. When triggered, do the following:

1. Gather today's top technology news from reputable sources.
1. Summarize the stories in a concise HTML email body.
1. Email the summary to $TO_EMAIL with the subject "Daily Tech News Summary".

O front matter declara como o agente é invocado. O corpo de markdown é o bloco de instrução que o runtime passa para o modelo durante a execução. A substituição de variável de ambiente permite que instruções e valores de configuração referenciem configurações de aplicativo, como $TO_EMAIL.

Cada .agent.md arquivo define um agente. O nome do arquivo é usado para definir o nome da Azure Function e o segmento de rota dos pontos de extremidade integrados. O name campo é um nome de exibição usado em logs, rótulos e documentação.

Use estes campos de front matter para configurar um agente:

Campo Obrigatório Description
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 habilitado Define como o agente é invocado. Somente um gatilho é permitido por arquivo de agente.
model No Substitui o modelo padrão configurado em agents.config.yaml ou nas configurações do aplicativo.
timeout No Substitui o tempo limite de execução padrão, em segundos.
builtin_endpoints No Habilita endpoints 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.
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.
skills No Controla o acesso às habilidades descobertas. Use false para desabilitar as habilidades deste agente ou exclude para remover habilidades específicas.
tools No Controla o acesso a ferramentas de Python personalizadas descobertas. Use false para desativar as ferramentas personalizadas deste agente ou use exclude para remover ferramentas específicas.
system_tools No Permite que um agente opte por não usar ferramentas do sistema configuradas, como execução em área restrita.
input_schema No JSON Schema usado para validar corpos de requisições HTTP para agentes acionados por HTTP.
response_schema No Esquema JSON usado para validar respostas estruturadas retornadas por agentes disparados por HTTP.
response_example No Formato de resposta de exemplo usado para orientar respostas estruturadas de agentes acionados por HTTP.
metadata No Metadados personalizados para sua própria organização ou ferramentas.
substitute_variables No Controla se a substituição de variáveis de ambiente é aplicada ao cabeçalho e às instruções. Usa true como padrão.

Padrões de runtime em 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.

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

Campo Obrigatório Description
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 Endpoint de gerenciamento para o pool dinâmico de sessões do Aplicativos de Contêiner do Azure usado 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/.

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. Use $SETTING_NAME ou %SETTING_NAME%. 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"
    }
  }
}

A substituição se aplica a valores de cadeia de caracteres, incluindo cadeias de caracteres aninhadas em objetos ou listas. Ele não se aplica a chaves de 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%.

Use $$SETTING_NAME ou %%SETTING_NAME%% quando precisar de um marcador literal no conteúdo substituído. As variáveis de ambiente ausentes são deixadas inalteradas, os valores vazios são resolvidos para cadeias de caracteres vazias e a substituição é uma única passagem. A sintaxe ${SETTING_NAME} não é compatível.

Para desativar a substituição dos metadados iniciais e das instruções de um agente, defina substitute_variables: false no arquivo do agente. Essa configuração não desativa a substituição em agents.config.yaml ou mcp.json.

Como o runtime inicia um aplicativo

Quando o host Azure Functions importa o aplicativo, create_function_app() cria um FunctionApp configurado dos arquivos do projeto:

  1. Resolva a raiz do aplicativo.
  2. Carregar agents.config.yaml.
  3. Carregue cada arquivo .agent.md.
  4. Descubra servidores MCP, habilidades e ferramentas personalizadas.
  5. Defina as configurações padrão do aplicativo e as configurações por agente.
  6. Valide a configuração do agente resolvido.
  7. Crie a ferramenta final e os recursos de habilidade para cada agente.
  8. Registre os gatilhos do Azure Functions e os pontos de extremidade internos opcionais.

Após a inicialização, o host Azure Functions indexa os gatilhos registrados da mesma forma que faz para outros aplicativos de funções. Quando um gatilho é acionado, o runtime cria o agente com suas instruções, configuração de modelo, ferramentas, habilidades e histórico de sessão e, em seguida, executa-o por meio do Microsoft Agent Framework.

Disparar agentes de eventos

Agentes sem servidor são úteis quando o evento que inicia o trabalho é tão importante quanto a chamada de modelo. O runtime dá suporte a um gatilho por arquivo de agente.

Uma definição de gatilho tem um objeto type e um objeto args. type identifica a vinculação de gatilho, e args contém as configurações específicas do gatilho que definem qual evento inicia o agente.

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

Os tipos de gatilho comuns incluem http_trigger, timer_trigger, queue_trigger, , blob_trigger, event_grid_triggere service_bus_trigger. Para gatilhos internos do Azure Functions, use a documentação de gatilhos e associações do Python v2 e a referência da associação do gatilho para encontrar as configurações a serem incluídas em args. Por exemplo, um gatilho de temporizador usa uma schedule configuração, um gatilho de fila usa configurações como queue_name e connection, e um gatilho de blob usa configurações como path e connection. O runtime fornece o ponto de entrada da função gerada, portanto, o arquivo do agente só precisa das configurações de gatilho que identificam a origem do evento.

Os padrões de gatilho comuns incluem:

Pattern Example
Agente HTTP Receber uma solicitação, chamar ferramentas e retornar uma resposta estruturada.
Agente agendado Execute um relatório diário, resumo, limpeza ou fluxo de trabalho de reconciliação.
Fila ou agente de mensagens Processar itens de trabalho que precisam de raciocínio de modelo ou chamadas de ferramenta.
Agente de eventos de armazenamento ou banco de dados Reagir a arquivos, registros ou eventos alterados.
Agente acionado pelo conector Reaja a eventos de serviços conectados, como mensagens do Teams, emails do Outlook ou eventos de calendário, quando houver suporte do conector.

Como cada agente é registrado como uma função Azure, o aplicativo pode usar recursos de hospedagem do Functions, como regras de escala, identidade gerenciada, rede e monitoramento.

Fornecer ferramentas de agentes

Os agentes se tornam úteis quando podem agir. Comece com recursos configurados: servidores MCP remotos, servidores MCP hospedados em namespaces do conector, habilidades e execução em área restrita. Use ferramentas de Python personalizadas para recursos específicos do aplicativo que não se encaixam nessas opções.

Servidores MCP remotos

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.

Use estes campos em cada servers entrada:

Campo Obrigatório Description
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.

Use servidores MCP remotos quando os agentes precisarem chamar ferramentas hospedadas por outro serviço ou compor agentes e ferramentas entre os limites do aplicativo.

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 conector em um aplicativo de agentes sem servidor, primeiro crie um Namespace do Conector, 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 as ferramentas MCP do conector, uma entrada de servidor MCP em mcp.json armazena o ponto de extremidade e as configurações de autenticação de identidade gerenciada. 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.

Habilidades

As habilidades são recursos de prompt reutilizáveis armazenados 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 .

O runtime examina skills/ a raiz do projeto do aplicativo de funções 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 metadados no cabeçalho em YAML, seguidos por 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).

Use estas regras de criação de habilidades:

  • Cada pasta de habilidade deve conter um arquivo SKILL.md.
  • Os campos name e description são obrigatórios.
  • Os nomes de habilidades devem usar letras minúsculas, números e hifens únicos. 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.
  • Há suporte apenas para arquivos markdown como conteúdo de habilidade no runtime de agentes sem servidor. Se uma habilidade precisar de comportamento executável, empacote esse código como uma ferramenta de Python personalizada e consulte a ferramenta pelo nome das instruções de habilidade.

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.

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

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Use estes requisitos de sandbox:

  • O pool de sessões deve ser um pool de sessões de interpretador de código em Python, como um pool criado com --container-type PythonLTS.
  • O valor de endpoint é o endpoint de gerenciamento do pool de sessões.
  • Em Azure, a identidade gerenciada usada pelo aplicativo de funções deve ter as atribuições de função necessárias para executar o 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.

Os agentes herdam a execução em área restrita quando ela é configurada globalmente. Desabilite-o para um agente específico quando esse agente não deve executar o código:

system_tools:
  dynamic_sessions_code_interpreter: false

Ferramentas de Python personalizadas

Use ferramentas Python personalizadas para recursos específicos do aplicativo que não se enquadram em servidores MCP, servidores MCP hospedados em namespaces de conectores, habilidades ou execução isolada. As ferramentas personalizadas permitem que você use pacotes Azure Functions e Python do mesmo aplicativo de funções.

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.

Você pode definir uma ferramenta decorando uma função com @tool do pacote de 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.

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

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

A seleção do provedor é baseada nas configurações do aplicativo. Você pode fixar o provedor com AZURE_FUNCTIONS_AGENTS_PROVIDER, ou permitir que o runtime infera o provedor de configurações como AZURE_OPENAI_ENDPOINT, FOUNDRY_PROJECT_ENDPOINTou OPENAI_API_KEY.

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. AZURE_FUNCTIONS_AGENTS_MODEL.
  4. O padrão do provedor.

Para aplicativos de produção, prefira a identidade gerenciada quando houver suporte. Quando um aplicativo deve usar uma identidade gerenciada atribuída pelo usuário, defina AZURE_CLIENT_ID para que os provedores de modelo e a execução em área restrita usem essa identidade.

Configurar identidades gerenciadas

O runtime usa a identidade gerenciada para recursos de Azure que dão suporte à autenticação Microsoft Entra. Use AZURE_CLIENT_ID como seletor de identidade padrão do aplicativo. Os servidores MCP hospedados em namespaces de conectores e o histórico de sessão com suporte de blobs podem usar configurações de identidade mais específicas.

Para provedores de modelo e execução em área restrita, defina AZURE_CLIENT_ID quando quiser que o runtime use uma identidade gerenciada atribuída pelo usuário. Se AZURE_CLIENT_ID não estiver definido, o runtime usará o comportamento de credencial de SDK do Azure padrão, que pode incluir a identidade gerenciada atribuída pelo sistema quando uma estiver disponível.

Use estas configurações para selecionar identidades gerenciadas:

Recurso de tempo de execução Configuração de identidade Alternativa
Provedor de modelo do Azure OpenAI AZURE_CLIENT_ID Comportamento padrão das credenciais
provedor de modelos do Fábrica de IA do Azure AZURE_CLIENT_ID Comportamento padrão das credenciais
Aplicativos de Contêiner do Azure área restrita de sessões dinâmicas system_tools.dynamic_sessions_code_interpreter.client_id AZURE_CLIENT_ID, em seguida, comportamento de credencial padrão
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, em seguida, comportamento de credencial padrão
Histórico de sessão com backup de blob AzureWebJobsStorage__clientId ao usar o armazenamento baseado em identidade AZURE_CLIENT_ID, em seguida, comportamento de credencial padrão

Para Azure OpenAI, essas configurações de identidade se aplicam somente quando AZURE_OPENAI_API_KEY não está definido. Se uma chave de API estiver configurada, o provedor de modelos usará a chave em vez da identidade gerenciada.

O histórico de sessão usa a mesma configuração de identidade de armazenamento que o host 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.

Sessões e estado

Interações de agente de vários turnos precisam de histórico de sessão. Em Azure, o runtime armazena o histórico de sessão em Armazenamento de Blobs usando a conta AzureWebJobsStorage do aplicativo de funções. Esse design evita um banco de dados de sessão separado para muitos aplicativos e funciona com configuração de armazenamento baseada em string de conexão ou em identidade.

Para o desenvolvimento local sem configuração de armazenamento do Azure, o ambiente de execução pode recorrer ao histórico de sessão baseado em arquivos no diretório de configuração dos agentes locais.

A execução em área restrita também tem reconhecimento de sessão. Quando o runtime cria ferramentas de área restrita sem uma ID de sessão explícita, ele usa uma sessão isolada para a invocação em vez de compartilhar o estado entre execuções de agente não relacionadas.

Pontos de extremidade internos

O ambiente de execução pode expor endpoints integrados de depuração e composição sem código adicional no aplicativo. Use a interface do usuário de chat e as APIs de chat para desenvolvimento, teste e diagnóstico, não como a interface do aplicativo de produção principal.

Superfície Rota chave do Azure
Interface do usuário do chat /agents/<AGENT_NAME>/ quando builtin_endpoints.debug_chat_ui: true Solicita uma chave de função quando hospedada no Azure.
HTTP chat API POST /agents/<AGENT_NAME>/chat quando builtin_endpoints.chat_api: true Chave de função.
Streaming chat API POST /agents/<AGENT_NAME>/chatstream quando builtin_endpoints.chat_api: true Chave de função.
Ponto de extremidade MCP /runtime/webhooks/mcp mcp_extension chave do sistema.

Qualquer arquivo de agente pode optar por isso por meio das configurações em seu cabeçalho builtin_endpoints. O <AGENT_NAME> segmento de rota é derivado do nome do .agent.md arquivo, não do campo de exibição name . Por exemplo, main.agent.md usa /agents/main/.

Quando hospedada no Azure, a interface do usuário do chat solicita uma chave de função antes de enviar mensagens. Você também pode usar essa chave para chamar as APIs de chat HTTP diretamente:

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

Passe a chave no cabeçalho x-functions-key ou no parâmetro da string de consulta code. Para conectar um cliente MCP, obtenha a chave do sistema de extensão MCP em vez disso:

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

O ponto de extremidade MCP requer essa chave do sistema, a menos que o aplicativo configure o acesso anônimo.

Quando usar o runtime de agentes sem servidor

Use o runtime de agentes sem servidor quando seu agente for orientado por eventos, rico em ferramentas ou operacionalmente próximo das cargas de trabalho do Azure Functions.

Os bons ajustes incluem:

  • Agentes em segundo plano agendados que resumem, monitoram, reconciliam ou geram relatórios.
  • Assistentes controlados por eventos que reagem a mensagens, emails, alertas, mensagens de fila ou alterações de dados.
  • Agentes multissistema que usam conectores para coordenar o trabalho entre aplicativos SaaS e corporativos.
  • Interfaces conversacionais que expõem o mesmo agente por meio de HTTP, interface de chat ou MCP.
  • Agentes que devem ser dimensionados para zero e usar identidade gerenciada, monitoramento, slots de implantação e outros recursos de hospedagem Azure.

Se você precisar expor apenas funções determinísticas como ferramentas para outro cliente de IA, a extensão mcp Azure Functions poderá ser um ponto de partida melhor. Para obter mais informações, consulte Usar ferramentas e modelos de IA no Azure Functions.

Introdução

Comece com o início rápido para implantar um aplicativo de agentes sem servidor com um agente de chat, um agente de resumo de blog disparado pelo temporizador, uma implantação de modelo, execução em área restrita e ferramentas MCP opcionais de um namespace do conector: