Guia para programadores de competências alojadas nas Funções do Azure

As competências alojadas no Funções do Azure utilizam um modelo de programação Markdown-first no runtime Python do Funções do Azure. Define cada habilidade alojada num ficheiro .agent.md. O front matter YAML define a sua configuração. O corpo Markdown dá instruções ao modelo.

A maior parte do trabalho de desenvolvimento altera estas definições e os respetivos ficheiros de ferramentas e de configuração. Normalmente não precisas de alterar o código de arranque gerado pelas Functions. No entanto, a aplicação ainda precisa das definições corretas do host, dependências de Python, acesso ao modelo e permissões de serviço.

Este guia utiliza o pacote azurefunctions-agents-runtimede pré-visualização pública . Para uma configuração local completa, comece pelo canvas quickstart. Para criar recursos do Azure e implementar um exemplo, use o quickstart da CLI do Azure Developer.

Estrutura do projeto

Utilize a seguinte estrutura na raiz do projeto da aplicação de funções. Adiciona os ficheiros opcionais apenas quando a tua aplicação precisa deles.

<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

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

from azure_functions_agents import create_function_app

app = create_function_app()

O runtime descobre as skills alojadas e as suas capacidades configuradas quando o host do Functions carrega a aplicação. Mantém os ficheiros de host e dependências do teu projeto de arranque. Para os ficheiros padrão de aplicações Python, consulte o guia para programadores em Python.

Defina uma skill alojada

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.

Esta definição aceita pedidos HTTP POST na summarize rota. No Azure, http_auth: function requer uma chave de função ou de anfitrião. O prefixo padrão da rota Functions é api, pelo que a rota é normalmente /api/summarize. Não uses um teste local para confirmar a autenticação em produção. Para detalhes, veja autorização do acionador HTTP.

O nome do ficheiro fornece a identidade da skill alojada. Para summarize.agent.md, o nome gerado da Função Azure é summarize, e o segmento de rota do endpoint incorporado é summarize. O campo name é um nome a apresentar. Uma alteração nesse campo não muda o nome da função. Um HTTP routeexplícito, como neste exemplo, define a rota do acionador HTTP.

O bloco builtin_endpoints ativa a janela de chat e as APIs de chat de apoio para testes locais. Para endpoints disponíveis e definições de autenticação, consulte endpoints incorporados.

Escreva instruções claras

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

As instruções não são controlos de acesso. Valide regras de negócio exatas, permissões e aprovações necessárias no código ou no serviço que executa 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 partilhados e substituições

Defina os padrões de modelo partilhado e timeout no agents.config.yaml:

model: $FOUNDRY_MODEL
timeout: 900

Defina FOUNDRY_MODEL para uma implementação do modelo disponível através do seu fornecedor configurado. Para um exemplo completo de definições da aplicação Foundry, veja Configurar definições locais. Para outros fornecedores, consulte configuração do fornecedor de modelo.

Adicione sobreposições suportadas para os padrões definidos em agents.config.yaml no front matter quando a skill alojada precisa de definições diferentes:

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

Este exemplo define um tempo limite de execução de 120 segundos, remove um servidor MCP e desativa competências reutilizáveis para esta competência alojada. O nome do servidor excluído deve corresponder a uma chave em mcp.json.

Use $SETTING_NAME para inserir uma definição de aplicação num valor de cadeia suportado. Por exemplo, model: $FOUNDRY_MODEL lê a configuração do modelo. Esta sintaxe não é sintaxe de expressão shell completa. Para regras de substituição, veja substituição de variáveis.

Definir um gatilho

Utilize um gatilho explícito em cada ficheiro .agent.md que comece com um evento. Para processar mensagens da Armazenamento do Azure Queue em vez de pedidos HTTP, substitua o blocotrigger:

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

Também altere as instruções para descrever a entrada da mensagem da fila em vez de um corpo de pedido HTTP.

O connection valor é o nome de uma definição de aplicação ou o prefixo para uma coleção de definições baseada em identidade, não um segredo incorporado. Configura a ligação de armazenamento e as permissões separadamente. Para mais informações, veja Ligações de acionador de fila.

Escolha um gatilho para a fonte do evento:

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

Os endpoints de chat e MCP incorporados opcionais são separados do disparador explícito. Consulte endpoints incorporados para mais informações. Uma definição remota de servidor MCP em mcp.json não expõe a tua skill alojada como servidor MCP.

Ligar a um servidor MCP

Usa um servidor MCP remoto quando outro serviço já fornece as ferramentas de que precisas. Adicionar mcp.json à raiz do projeto da aplicação de funções:

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

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

As skills alojadas herdam servidores MCP descobertos, a menos que as excluas. Para excluir o servidor de uma skill alojada, defina mcp.exclude no .agent.md ficheiro. Para limitar um servidor a ferramentas específicas, adicione um tools array à sua entrada em mcp.json. Utilize os nomes exatos das ferramentas publicados nesse servidor. Esta seleção aplica-se à definição do servidor.

Para autenticação Microsoft Entra, defina auth.scope para o âmbito do token do servidor. Também pode definir auth.client_id para selecionar uma identidade gerida atribuída pelo utilizador. A identidade selecionada deve ter permissão para chamar o servidor. Não coloques segredos em mcp.json. Para mais detalhes, veja configuração do servidor MCP.

A execução alojada é não interativa. Esta configuração baseada em identidade não executa automaticamente um fluxo OAuth interativo do utilizador. Se um serviço empresarial exigir autorização delegada do utilizador, considere um conector suportado e a sua conexão gerida. Confirme que o conector suporta o modelo de autorização exigido pelo serviço. Veja Usar conectores Azure.

Reutilizar instruções com skills

Use uma skill reutilizável para orientação de que várias skills alojadas necessitam, ou para material de referência que não seja necessário em todos os pedidos.

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 secções obrigatórias do relatório. Em assets/example-report.md, dê um relatório de exemplo que mostre o formato.

A habilidade name 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 a pedido. Menciona recursos de suporte em SKILL.md para que a capacidade alojada saiba quando os deve ler.

Mantenha cada habilidade na sua própria pasta diretamente abaixo de skills/. Para orientações de autoria, consulte Skills.

Os ficheiros de skill não registam automaticamente ferramentas executáveis. Use uma ferramenta configurada para comportamento executável. Não assumas que um script numa skill dá permissão ao modelo ou uma forma de o executar.

Adicionar ferramentas

Primeiro, use uma ferramenta MCP remota ou uma ferramenta do sistema de runtime se cumprir os requisitos. Adicione ferramentas Python personalizadas para lógica específica da aplicação.

Ferramentas do sistema de runtime

O runtime ativa a web_request ferramenta do sistema por defeito. Faz pedidos de saída para endereços web públicos. O HTTPS é obrigatório por defeito. Para restringir os pedidos 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 toda a aplicação ou para uma skill alojada. Uma lista de permissão restringe os destinos. Não concede permissão para usar um serviço nem enviar dados confidenciais.

Para execução isolada em Python, configure um pool de interpretadores de código Python para sessões dinâmicas do Azure Container Apps:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Definir ACA_SESSION_POOL_ENDPOINT para o endpoint de gestão do pool. Conceda à identidade da aplicação as permissões necessárias para o pool antes de a usar. Para definições e requisitos de identidade, veja execução em sandbox.

Ferramentas personalizadas de Python

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 ficheiro em tools/. O runtime regista a primeira ferramenta comum suportada que encontra em cada ficheiro. Use anotações de tipo e uma docstring transparente para que o modelo possa compreender o propósito e as entradas da ferramenta. Adicione quaisquer pacotes necessários a requirements.txt.

Uma ferramenta Python personalizada corre no Worker Functions Python. Não está automaticamente isolado num sandbox. Validar entradas, aplicar permissões e reportar falhas explicitamente. Para ferramentas que alteram o estado externo, torne as chamadas repetidas seguras, por exemplo usando uma chave de idempotência.

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

Gerir a configuração

As definições locais não são copiadas automaticamente para as definições da aplicação Azure. Configure ambos os ambientes. Mantenha os segredos fora do Git, use identidade gerida onde for suportado e use armazenamento adequado de segredos para credenciais que ainda são necessárias. Consulte as definições locais e gere as definições da aplicação.

As skills timeout alojadas e as do anfitrião functionTimeout do Functions são limites separados. Defina ambos para a sua carga de trabalho. Um timeout de skill hospedado não se sobrepõe a limites de planos de alojamento ou de resposta HTTP. Veja a duração do tempo limite da Function App.

Usar conectores Azure

Os conectores Azure permitem que skills alojadas chamem operações externas autorizadas e recebam eventos de serviço sem código personalizado de cliente e de autenticação. Esta secção assume que os recursos do conector já existem.

Para configurar um servidor MCP e a sua ligação, veja Criar um conector de 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 implementado nas definições locais ou da aplicação Azure. Conceda à identidade da aplicação de funções acesso a esse servidor MCP. Para selecionar uma identidade gerida atribuída pelo utilizador, adicione auth.client_id com o seu ID de cliente.

Configure os dois limites de autorização:

Permissão numa fronteira não concede permissão na outra. A autorização da ligação não se torna automaticamente a identidade de cada chamador da tua skill alojada.

Para iniciar uma skill alojada a partir de um evento de conector, primeiro crie e autorize uma conexão. Depois usa este bloco de gatilho no ficheiro .agent.md correspondente:

trigger:
  type: connector_trigger

Também deve configurar o evento a montante, o encaminhamento de callback e a autenticação de callback no Connector Namespace. Uma definição de servidor em mcp.json não subscreve eventos. Para requisitos de extensão e configuração de eventos, consulte Usar conectores geridos no Funções do Azure.

Executar localmente

Use o Funções do Azure Core Tools para iniciar a aplicação no seu computador. Também precisas de Python 3.13 ou posterior e acesso a um deployment do modelo.

Definir configurações locais

Criar local.settings.json na raiz do projeto da 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 marcadores de endpoint e modelo pelos valores de implantação. Use uma implementação de modelo que exista no seu projeto Foundry e conceda à identidade do seu programador local acesso à mesma. Adiciona quaisquer configurações usadas pelos teus servidores, ferramentas ou triggers MCP. Mantenha local.settings.json fora do controlo de versão.

Utilize um emulador como fonte de dados quando estiver disponível um emulador compatível. Por exemplo, o Azurite fornece armazenamento local de Blob, Queue e Table. Inicie o Azurite antes do anfitrião Functions quando usar UseDevelopmentStorage=true. Para obter informações sobre o Service Bus, veja o emulador Service Bus.

Os namespaces de conector, as conexões e os servidores MCP de conector requerem recursos reais do Azure. A execução local ainda invoca esses recursos. As chamadas de modelo e as sessões dinâmicas do Azure Container Apps também utilizam os seus serviços configurados e podem incorrer em encargos.

Iniciar o host do Functions

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

python -m pip install -r requirements.txt

Para Foundry com acesso baseado em identidade, inicie sessão 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 anfitrião lista a summarize função e os endpoints incorporados habilitados pelo exemplo. Com o prefixo de rota 7071 predefinido e a porta 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

Mantém o host a funcionar enquanto testas. Leia a saída do terminal para erros de configuração e as URLs das funções registadas. 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 incorporada e as APIs de chat de apoio.

Abre http://localhost:7071/api/agents/summarize/ no teu navegador quando host.json usa o prefixo de rota por defeito api. Se o teu projeto inicial define extensions.http.routePrefix como uma cadeia vazia, usa http://localhost:7071/agents/summarize/ em vez disso. Use a porta real do host, se for diferente de 7071.

Introduza um pedido de exemplo, envie-o e inspecione a resposta e o registo do host. Por exemplo, peça à habilidade alojada para resumir um pedido com uma data de entrega em falta. Verifique se a resposta identifica a data em falta em vez de inventar uma. Teste também a entrada em falta e as falhas das ferramentas.

A execução local do Core Tools normalmente ignora as verificações das teclas de função. Mantém http_auth: function na definição e testa a autenticação separadamente no Azure. Para uma janela de chat publicada, introduza a chave de função quando solicitado. Ativa os endpoints de depuração apenas onde necessário. Para rotas e recuperação de chaves, consulte os endpoints incorporados.

Publicar no Azure

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

Após a implementação, confirme que as definições da aplicação no Azure contêm os valores necessários, que a identidade da aplicação tem acesso ao modelo e às ferramentas, e que cada ligação de conector está autorizada. Teste o gatilho implementado e a sua autenticação com um pedido controlado antes de usar dados de produção.

Explorar exemplos completos

Utilize estes exemplos para ver como as skills alojadas combinam gatilhos, ferramentas e serviços do Azure numa aplicação completa. Cada repositório inclui instruções de configuração e implantação.

Conteúdo relacionado

• Descrição geral das competências alojadas em Funções do Azure
• Referência de configuração de competências alojadas
• Criar e testar com o painel alojado de competências
• Coloque em produção uma aplicação de competências alojada orientada a eventos
• Construir fluxos de trabalho dinâmicos
• Orientação de observabilidade em tempo de execução
• Exemplos de competências alojadas