Guia para desenvolvedores de habilidades hospedadas no Azure Functions

As habilidades hospedadas no Azure Functions utilizam um modelo de programação Markdown-first no runtime do Python do Azure Functions. Você define cada habilidade hospedada em um .agent.md arquivo. O front matter YAML define a configuração. O corpo Markdown fornece instruções para o modelo.

A maior parte do trabalho de desenvolvimento altera essas definições e seus arquivos de ferramentas e seus arquivos de configuração. Normalmente, você não precisa mudar o código de inicialização gerado pelo Functions. No entanto, o app ainda precisa das configurações corretas de host, dependências de Python, acesso a modelos e permissões de serviço.

Importante

As habilidades hospedadas no Azure Functions estão atualmente em versão prévia. Recursos, nomes de configuração e conectores com suporte podem ser alterados antes da disponibilidade geral.

Este guia utiliza o pacote azurefunctions-agents-runtime em versão preliminar pública. Para uma configuração local completa, comece pelo quickstart do canvas. Para criar recursos do Azure e implantar um exemplo, use o guia de início rápido da CLI do Azure Developer.

Note

Um .agent.md arquivo define uma habilidade hospedada, que pode ser executada quando ocorre um evento. Um SKILL.md arquivo define uma skill reutilizável, que fornece instruções e material de referência para uma skill hospedada. Esses arquivos têm propósitos diferentes.

Estrutura do Projeto

Use a estrutura a seguir na raiz do projeto do app de funções. Adicione os arquivos opcionais apenas quando seu app precisar.

<project_root>/
├── function_app.py
├── host.json
├── requirements.txt
├── local.settings.json
├── summarize.agent.md
├── agents.config.yaml
├── mcp.json
├── skills/
│   └── report-writing/
│       ├── SKILL.md
│       ├── references/
│       │   └── report-format.md
│       └── assets/
│           └── example-report.md
└── tools/
    └── get_policy.py
Arquivo ou pasta Purpose
function_app.py Cria o aplicativo Functions e inicia a descoberta em tempo de execução.
host.json Define as opções de host do Azure Functions, como pacotes de extensão e o timeout da função.
requirements.txt Lista o runtime das habilidades hospedadas e outras dependências do Python.
local.settings.json Armazena as configurações locais do aplicativo. Não adicione segredos a este arquivo.
summarize.agent.md Define uma habilidade hospedada, seu gatilho e suas instruções.
agents.config.yaml Configurações padrão opcionais para o tempo de execução em todo o app.
mcp.json Definições opcionais de servidores MCP remotos.
skills/ Habilidades opcionais reutilizáveis e seus recursos Markdown.
tools/ Ferramentas opcionais de Python personalizadas.

O código function_app.py inicial pode ser tão pequeno quanto este:

from azure_functions_agents import create_function_app

app = create_function_app()

O runtime descobre skills hospedadas e suas capacidades configuradas quando o host de Funções carrega o app. Guarde os arquivos de host e dependência do seu projeto inicial. Para os arquivos padrão de aplicativos Python, veja o guia para desenvolvedores em Python.

Defina uma habilidade hospedada

Crie summarize.agent.md na raiz do projeto:

---
name: Request summary
description: Summarize a request and identify missing information.
trigger:
  type: http_trigger
  args:
    route: summarize
    methods: [POST]
    http_auth: function
builtin_endpoints:
  debug_chat_ui: true
  http_auth: function
---

Summarize the request supplied in the HTTP request body.

Return these sections:

- Summary: State the purpose of the request.
- Missing information: List the facts needed to complete the request.
- Questions: Ask specific questions for the missing facts.

Use only the supplied facts. Do not invent names, dates, or approvals.
If the request is empty or unclear, explain what information is needed.

Essa definição aceita requisições HTTP POST na summarize rota. No Azure, http_auth: function requer uma função ou chave host. O prefixo padrão da rota Functions é api, então a rota é normalmente /api/summarize. Não use um teste local para confirmar a autenticação em produção. Para saber mais detalhes, confira Autorização de gatilho HTTP.

O nome do arquivo fornece a identidade da habilidade hospedada. Para summarize.agent.md, o nome gerado da função Azure é summarize, e o segmento de rota do endpoint embutido é summarize. O name campo é um nome de exibição. Uma mudança nesse campo não renomeia a função. Um HTTP routeexplícito, como neste exemplo, define a rota de gatilho HTTP.

O bloco builtin_endpoints permite a janela de chat e suas APIs de chat de apoio para testes locais. Para pontos de extremidade disponíveis e configurações de autenticação, veja pontos de extremidade integrados.

Escreva instruções claras

Indique o objetivo, a entrada, as ferramentas a usar e a saída necessária. Explique o que fazer quando os dados faltam ou uma ferramenta falha. Declare quais ações a habilidade hospedada não deve realizar.

Instruções não são controles de autorização. Valide regras exatas de negócio, permissões e aprovações necessárias no código ou no serviço que realiza a ação. Por exemplo, um prompt que diz "enviar apenas relatórios aprovados" não substitui uma verificação de aprovação na ferramenta que envia o relatório.

Configurar padrões compartilhados e sobrescritos

Defina os padrões compartilhados de modelo e de timeout em agents.config.yaml:

model: $FOUNDRY_MODEL
timeout: 900

Defina FOUNDRY_MODEL para uma implantação de modelo disponível pelo seu provedor configurado. Para um exemplo completo de configurações do app Foundry, veja Configurar configurações locais. Para outros provedores, veja configuração do provedor de modelo.

Adicione overrides suportados para os padrões definidos em agents.config.yaml no front matter quando a habilidade hospedada precisar de configurações diferentes:

timeout: 120
mcp:
  exclude:
    - office365-outlook
skills: false

Este exemplo estabelece um tempo de execução de 120 segundos, remove um servidor MCP e desativa habilidades reutilizáveis para essa habilidade hospedada. O nome do servidor excluído deve corresponder a uma chave em mcp.json.

Use $SETTING_NAME para inserir uma configuração de aplicativo em um valor de string compatível. Por exemplo, model: $FOUNDRY_MODEL lê a configuração do modelo. Essa sintaxe não é a sintaxe de expressão shell completa. Para regras de substituição, veja substituição de variáveis.

Configure um gatilho

Use um gatilho explícito em cada arquivo .agent.md que comece com um evento. Para processar mensagens da Armazenamento do Azure Queue em vez de requisições HTTP, substitua o blocotrigger:

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

Também mude as instruções para descrever a entrada da mensagem da fila em vez de um corpo de requisição HTTP.

O connection valor é o nome de uma configuração de aplicativo ou o prefixo para uma coleção de configurações baseada em identidade, não um segredo embutido. Configure a conexão de armazenamento e as permissões separadamente. Para mais informações, veja Conexões de disparo de fila.

Escolha um gatilho para a fonte do evento:

Origem do Evento Usar
solicitação HTTP http_trigger para uma solicitação e uma resposta.
Schedule timer_trigger com agendamento por temporizador.
Fila ou Barramento de Serviço Uma fila ou gatilho de mensagem para itens de trabalho.
Mudança de blob ou banco de dados O gatilho para o serviço de armazenamento ou banco de dados.
Evento de serviço externo connector_trigger com uma fonte de evento de conector configurada.

Para a lista completa e os argumentos obrigatórios, veja tipos de gatilhos suportados.

Os endpoints opcionais de chat e MCP integrados são separados do gatilho explícito. Veja endpoints integrados para mais informações. Uma definição remota de servidor MCP em mcp.json não expõe sua skill hospedada como servidor MCP.

Conecte um servidor MCP

Use um servidor MCP remoto quando outro serviço já forneça as ferramentas que você precisa. Adicionar mcp.json à raiz do projeto do aplicativo de funções:

{
  "servers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

O runtime suporta transportes remotos http e streamable-http. Ele não inicia servidores MCP locais stdio ou baseados em comandos.

Habilidades hospedadas herdam servidores MCP descobertos, a menos que você os exclua. Para excluir o servidor de uma habilidade hospedada, defina mcp.exclude no .agent.md arquivo. Para limitar um servidor a ferramentas específicas, adicione um tools array à sua entrada em mcp.json. Use os nomes exatos das ferramentas publicadas por esse servidor. Essa seleção se aplica à definição de servidor.

Para autenticação Microsoft Entra, defina auth.scope para o escopo do token do servidor. Você também pode configurar auth.client_id para selecionar uma identidade gerenciada atribuída pelo usuário. A identidade selecionada deve ter permissão para chamar o servidor. Não coloque segredos em mcp.json. Para detalhes, veja configuração do servidor MCP.

A execução hospedada não é interativa. Essa configuração baseada em identidade não executa automaticamente um fluxo OAuth interativo do usuário. Se um serviço empresarial exigir autorização delegada do usuário, considere um conector suportado e sua conexão gerenciada. Confirme que o conector suporta o modelo de autorização exigido pelo serviço. Consulte Usar conectores do Azure.

Reutilizar instruções com habilidades

Use uma habilidade reutilizável para instruções de que várias habilidades hospedadas precisam, ou para material de referência que não é necessário em todas as solicitações.

Criar skills/report-writing/SKILL.md:

---
name: report-writing
description: Write a review report from supplied facts. Use when a task requests a review report.
---

Read [the report format](references/report-format.md) before you write.
Use [the example report](assets/example-report.md) as a format example,
not as a source of facts.

State the result, the supporting facts, and the questions that remain.
If required facts are missing, list them. Do not invent a result.

Em references/report-format.md, defina as seções obrigatórias do relatório. Em assets/example-report.md, forneça um relatório de exemplo que mostra o formato.

O name da habilidade deve corresponder ao diretório que a contém, como report-writing. O runtime fornece nomes de habilidades e descrições para descoberta e carrega instruções e recursos completos sob demanda. Mencione recursos de suporte em SKILL.md para que a habilidade hospedada saiba quando deve lê-los.

Mantenha cada habilidade em sua própria pasta diretamente sob skills/. Para diretrizes de autoria, veja Skills.

Arquivos de habilidades não registram automaticamente ferramentas executáveis. Use uma ferramenta configurada para comportamento de execução. Não presuma que um script em uma habilidade dá permissão ao modelo ou uma forma de executá-lo.

Adicionar ferramentas

Primeiro, use uma ferramenta MCP remota ou uma ferramenta de sistema em tempo de execução se atender ao requisito. Adicionar ferramentas Python personalizadas para lógica específica de aplicativo.

Ferramentas do sistema em tempo de execução

O runtime ativa a ferramenta do sistema web_request por padrão. Ele faz requisições de saída para endereços públicos da Web. HTTPS é exigido por padrão. Para restringir as requisições a um nome de host exato, adicione esta configuração a:agents.config.yaml

system_tools:
  web_request:
    allowed_hosts:
      - example.com

Defina system_tools.web_request: false para desativar a ferramenta em todo o app ou para uma habilidade hospedada. Uma lista de permissão restringe os destinos. Não concede permissão para usar um serviço ou enviar dados confidenciais.

Para execução isolada em Python, configure um pool de interpretadores de código Python de sessões dinâmicas dos Aplicativos de Contêiner do Azure:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Definir ACA_SESSION_POOL_ENDPOINT para o endpoint de gerenciamento da pool. Conceda à identidade do app as permissões necessárias do pool antes de usá-la. Para configurações e requisitos de identidade, veja execução em sandbox.

Ferramentas de Python personalizadas

Criar tools/get_policy.py:

from azure_functions_agents import tool


@tool
def get_policy_version() -> str:
    """Return the version of the sample review policy."""
    return "2026-10"

Use uma ferramenta pública por arquivo .py em tools/. O runtime registra a primeira ferramenta comum suportada que encontra em cada arquivo. Use anotações de tipo e uma docstring clara para que o modelo possa entender o propósito e as entradas da ferramenta. Adicione quaisquer pacotes necessários a requirements.txt.

Uma ferramenta personalizada de Python roda no worker de Funções Python. Não é automaticamente isolado em um sandbox. Valide entradas, aplique permissões e relate falhas explicitamente. Para ferramentas que mudam o estado externo, torne as chamadas repetidas seguras, por exemplo, usando uma chave de idempotência.

Ferramentas de fluxo de trabalho duráveis usam um @workflow_tool contrato separado. Para esse modelo, veja Fluxos de trabalho dinâmicos.

Gerenciar configuração

As configurações locais não são copiadas automaticamente para as configurações do app do Azure. Configurar os dois ambientes. Mantenha segredos fora do Git, use identidade gerenciada onde for suportado e use armazenamento secreto apropriado para credenciais que ainda são necessárias. Veja as configurações locais e gerencie as configurações do aplicativo.

O timeout da habilidade hospedada e o functionTimeout do host do Functions são limites separados. Defina ambos para sua carga de trabalho. Um tempo limite de habilidade hospedada não substitui limites de planos de hospedagem ou de resposta HTTP. Consulte a duração do tempo limite do aplicativo de função.

Usar conectores do Azure

Conectores Azure permitem que habilidades hospedadas chamem operações externas autorizadas e recebam eventos de serviço sem cliente personalizado e código de autenticação. Esta seção assume que os recursos do conector já existem.

Para configurar um servidor MCP e sua conexão, veja Criar um conector para servidor MCP.

Para um servidor Microsoft 365 Outlook MCP existente, adicione uma entrada em mcp.json:

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

Defina O365_MCP_SERVER_URL para o endpoint do servidor implantado nas configurações locais ou do app Azure. Conceda à identidade do app de função acesso a esse servidor MCP. Para selecionar uma identidade gerenciada atribuída pelo usuário, adicione auth.client_id com seu ID de cliente.

Configure ambos os limites de autorização:

Limite Configuração necessária
Aplicativo Function para o servidor MCP do conector A identidade do app precisa de permissão para chamar o servidor MCP.
Conexão de conector com serviço externo A conexão deve ser autorizada para o usuário ou o serviço upstream e para as operações necessárias.

Permissão em uma fronteira não concede permissão na outra. A autorização da conexão não se torna automaticamente a identidade de cada chamador da sua habilidade hospedada.

Para iniciar uma habilidade hospedada a partir de um evento de conector, primeiro crie e autorize uma conexão. Depois use este bloco de gatilho em seu arquivo .agent.md:

trigger:
  type: connector_trigger

Você também deve configurar o evento upstream, o roteamento de callback e a autenticação de callback no Namespace do Conector. Uma definição de servidor em mcp.json não subscreve eventos. Para requisitos de extensão e configuração de eventos, veja Usar conectores gerenciados no Azure Functions.

Executar localmente

Use Azure Functions Core Tools para iniciar o aplicativo no computador. Você também precisa de Python 3.13 ou mais recente e acesso a uma implantação de modelo.

Configurar as configurações locais

Criar local.settings.json na raiz do projeto do Function App. Para um modelo Foundry e Armazenamento do Azure local, use esta estrutura:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AZURE_FUNCTIONS_AGENTS_PROVIDER": "foundry",
    "FOUNDRY_PROJECT_ENDPOINT": "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    "FOUNDRY_MODEL": "<model-deployment-name>"
  }
}

Substitua os pontos de extremidade e os espaços reservados de modelo pelos valores de implantação. Use uma implantação de modelo que exista no seu projeto Foundry e conceda à identidade de desenvolvedor local acesso a ela. Adicione quaisquer configurações usadas pelos seus servidores, ferramentas ou gatilhos do MCP. Mantenha local.settings.json fora do controle do código-fonte.

Use um emulador como fonte de dados quando um emulador compatível estiver disponível. Por exemplo, o Azurite oferece armazenamento local de Blob, Fila e Tabelas. Comece Azurite antes do host de Funções quando usar UseDevelopmentStorage=true. Para Barramento de Serviço, veja o emulador Barramento de Serviço.

Namespaces de conectores, conexões e servidores MCP de conectores exigem recursos reais do Azure. A execução local ainda chama esses recursos. Chamadas de modelo e sessões dinâmicas do Aplicativos de Contêiner do Azure também utilizam seus serviços configurados e podem incorrer em cobranças.

Iniciar o host de Funções

Crie e ative um ambiente virtual em Python conforme descrito no guia de desenvolvimento local em Python. Na raiz do projeto do app de funções, instale os pacotes a partir de requirements.txt:

python -m pip install -r requirements.txt

Para Foundry com acesso baseado em identidade, faça login com uma identidade que tenha permissão para usar o modelo:

az login

Inicie o host a partir do mesmo diretório:

func start

O host lista a summarize função e os endpoints embutidos habilitados pelo exemplo. Com o prefixo de rota padrão 7071 e a porta padrão api, a saída é semelhante a:

Functions:

    agent_summarize_builtin_chat: [POST] http://localhost:7071/api/agents/summarize/chat

    agent_summarize_builtin_chatstream: [POST] http://localhost:7071/api/agents/summarize/chatstream

    agent_summarize_builtin_chat_page: [GET] http://localhost:7071/api/agents/summarize/

    agent_summarize_builtin_history: [GET] http://localhost:7071/api/agents/summarize/history

    summarize: [POST] http://localhost:7071/api/summarize

Mantenha o host ativo enquanto testa. Leia a saída do terminal para erros de configuração e as URLs de funções registradas. Para obter mais informações, consulte Executar uma função local.

Teste com a janela de chat

O exemplo summarize.agent.md já ativa a janela de chat embutida e suas APIs de chat subjacentes.

Abra http://localhost:7071/api/agents/summarize/ no seu navegador quando host.json usar o prefixo padrão api de rota. Se seu projeto inicial definir extensions.http.routePrefix como uma string vazia, use http://localhost:7071/agents/summarize/ em vez disso. Use a porta real do host se ela for diferente de 7071.

Insira uma solicitação de exemplo, envie e inspecione a resposta e o log do host. Por exemplo, peça à habilidade hospedada para resumir uma solicitação com data de entrega faltante. Verifique se a resposta identifica a data faltante, em vez de inventar uma. Também teste entradas ausentes e falhas de ferramentas.

A execução do Local Core Tools normalmente pula as verificações de teclas de função. Mantenha http_auth: function na definição e teste a autenticação separadamente no Azure. Para uma janela de chat implantada, forneça a chave de função quando solicitado. Ative os endpoints de depuração apenas onde necessário. Para rotas e recuperação de chaves, veja endpoints embutidos.

Publicar no Azure

Escolha um método de implantação para seu projeto:

Method Guidance
Exemplo com um modelo Bicep Use o repositório de exemplos de habilidades hospedadas. Seu modelo de infraestrutura cria os recursos necessários. Siga o guia de início rápido da CLI do Azure Developer para configurar e executar azd up.
Azure Functions Hosted Skills canvas Use o canvas para criar e testar um app, depois selecione Implantar no Azure. Veja o início rápido da tela de habilidades hospedadas.
Azure Functions Skills Instale o Azure Functions Skills. Sua azure-functions-hosted-skills habilidade de autoria ajuda seu agente de programação a criar um aplicativo e preparar sua implantação. Peça ao agente de programação para implantar o app, depois revise os recursos, permissões e custos propostos antes de aprovar a implantação.

Após a implantação, confirme que as configurações do app do Azure contêm os valores necessários, que a identidade do app tem acesso ao modelo e às ferramentas, e que cada conexão de conector está autorizada. Teste o gatilho implantado e sua autenticação com uma requisição controlada antes de usar dados de produção.

Explore exemplos de ponta a ponta

Use estes exemplos para ver como habilidades hospedadas combinam gatilhos, ferramentas e serviços do Azure em um app completo. Cada repositório inclui instruções de configuração e implantação.

Sample O que ele demonstra
Revisão da apólice de seguro Inicie um fluxo de trabalho durável a partir de uma mensagem de fila, revise documentos em paralelo e salve um relatório no Armazenamento de Blobs para revisão humana.
Processador de despesas Processe despesas a partir de uma fila, leia documentos de política através de um servidor MCP conector e encaminhe os resultados para as filas de saída. Chamadas de modelo utilizam um gateway Gerenciamento de API do Azure AI.
Resumo diário do blog Use gatilhos de chat e temporizadores para resumir posts de blog com o interpretador de códigos das sessões dinâmicas dos Aplicativos de Contêiner do Azure. Opcionalmente, envie o resumo por um conector Microsoft 365 Outlook.