Quais são as competências hospedadas no Funções do Azure?

As competências alojadas no Funções do Azure permitem-te adicionar raciocínio de IA às tuas aplicações de funções. Num ficheiro .agent.md, especifica instruções em linguagem natural, uma configuração de acionamento e associações opcionais a ferramentas. Quando um evento é lançado, o runtime chama um modelo, executa as ferramentas que o modelo solicita e retorna um resultado. Implementas a aplicação como qualquer outra aplicação funcional.

Para começar, escolha a experiência que corresponde ao seu objetivo:

Para obter a documentação do runtime mais atualizada e abrangente, consulte Funções do Azure Agents Runtime.

Importante

As habilidades hospedadas do Funções do Azure estão atualmente em pré-visualização. Funcionalidades, nomes de configuração e conectores suportados podem mudar antes da disponibilidade geral.

Uma competência hospedada é uma única unidade de trabalho baseada em IA definida num ficheiro .agent.md. Cada habilidade alojada corresponde a uma Função Azure. Uma habilidade por si só refere-se a orientações Markdown reutilizáveis armazenadas num SKILL.md ficheiro que as competências alojadas podem carregar sob demanda.

Quando usar as competências hospedadas

Use competências alojadas no Funções do Azure quando um evento empresarial precisar de raciocínio por IA antes de tomar uma ação. Por exemplo:

  • Triagem de emails recebidos. Um gatilho de ligação é ativado quando uma queixa chega numa caixa de correio partilhada. A habilidade alojada lê a mensagem, classifica a gravidade e encaminha-a para a fila de suporte correta.
  • Enriqueça novos leads no CRM. Um gatilho de conector é ativado quando um lead é adicionado ao Salesforce ou ao Dynamics 365. A competência alojada procura na internet contexto sobre o lead e envia um resumo ao vendedor designado.
  • Validar alterações nos dados. Um acionador de blob ou de base de dados é acionado quando um registo de receitas é atualizado. A competência hospedada verifica se as receitas desceram abaixo de um valor limite, gera uma explicação e inicia um fluxo de revisão.
  • Disponibilize uma ferramenta MCP específica de um domínio. Um agente externo ou um orquestrador de agentes invoca uma capacidade hospedada através de HTTP ou MCP. A competência alojada aplica lógica de IA a dados em armazenamento ou numa base de dados e devolve uma resposta estruturada, atuando como uma ferramenta inteligente e específica de domínio que outros clientes de IA podem consumir.

As competências alojadas são uma boa opção quando precisa de acionadores acionados por eventos, raciocínio de IA com ferramentas e das funcionalidades operacionais do Funções do Azure (identidade gerida, monitorização, dimensionamento até zero e integração com redes virtuais).

Para exemplos que combinam eventos, raciocínio de IA e sistemas empresariais, veja cenários de competências alojadas no Funções do Azure.

Por que usar Funções para as suas aplicações de IA?

As cargas de trabalho de IA em produção precisam de mais do que um prompt e um modelo. Precisam de formas fiáveis para iniciar o trabalho, ligar para sistemas externos, persistir o histórico de conversas, executar código não confiável em segurança, autenticar sem segredos, emitir telemetria e escalar a pedido.

O Functions fornece um modelo de computação orientado a eventos para estas preocupações operacionais. As competências alojadas no Funções do Azure aplicam esse mesmo modelo ao teu código de IA. Os benefícios incluem:

  • Cada habilidade alojada corresponde a um ficheiro .agent.md. A configuração declarativa e as instruções em linguagem natural coexistem. Cada ficheiro corresponde a uma função Azure.
  • Os eventos iniciam competências alojadas. Os acionadores do Functions iniciam competências alojadas em resposta a agendamentos, pedidos HTTP, mensagens de fila, alterações em blobs, eventos do Event Grid, mensagens do Service Bus e outros eventos suportados.
  • As funcionalidades configuram-se primeiro, recorrendo a código apenas quando necessário. Pode configurar competências alojadas para usar servidores MCP remotos, servidores MCP alojados em namespaces de conectores, competências reutilizáveis e execução de código em sandbox. Escreve as tuas próprias ferramentas baseadas em Python para lógica específica de aplicações.
  • O alojamento do Funções do Azure está integrado. As competências alojadas no Funções do Azure suportam os planos Flex Consumption, Premium e Dedicated (App Service). O Flex Consumption oferece dimensionamento até zero, faturação por segundo e dimensionamento automático. Todos os planos suportam identidade gerida, integração com redes virtuais e Application Insights.
  • A canalização operacional é tratada por si. O runtime gere a descoberta de competências alojada, o registo de gatilhos, a montagem de ferramentas, o histórico de sessões e os endpoints opcionais incorporados.

Funciona com outras plataformas de IA da Microsoft

As competências alojadas no Funções do Azure são complementares a outras ofertas de IA da Microsoft e podem ser usadas em conjunto. O seu ponto ideal é construir capacidades inteligentes alojadas na cloud e orientadas por eventos no Funções do Azure através de um modelo de programação acessível. As competências hospedadas podem expor capacidades através de HTTP ou MCP para serem utilizadas por outras aplicações, agentes e estruturas de teste para agentes.

Escolha a funcionalidade Azure que melhor se adapta ao seu cenário:

Scenario Option
Expor funções determinísticas como ferramentas para outro cliente de IA extensão MCP do Funções do Azure
Orquestração de longa duração em vários passos com aprovações com intervenção humana Durable Functions
Criar e gerir agentes de IA sem alojamento personalizado Microsoft Foundry ou Copilot Studio

Definição do projeto

Uma aplicação de competências hospedada no Funções do Azure é um projeto padrão de aplicação de funções em Python v2, implementado juntamente com ficheiros de projetos de competências alojados. Os seguintes ficheiros de projeto são sempre necessários para aplicações de funções em Python:

File Purpose
function_app.py Importa create_function_app() e devolve a aplicação de Funções do Azure configurada.
host.json Configura o host do Funções do Azure.
requirements.txt Inclui o pacote de runtime de skills alojado e quaisquer dependências específicas de Python da aplicação.

Para mais informações, consulte o guia de referência para programadores do Funções do Azure para aplicações Python.

Importante

As skills alojadas do Funções do Azure suportam apenas funções de streaming HTTP. Quaisquer outras funções HTTP na mesma aplicação de competências alojada também devem usar streaming. Combinar funções HTTP de streaming e não-streaming dentro da mesma aplicação não é suportado. Para mais informações, consulte fluxos HTTP em Python.

Ficheiros de projetos de competências alojados

O runtime descobre estes ficheiros e pastas, que são implementados com o projeto da aplicação:

Ficheiro ou pasta Purpose
*.agent.md Define competências hospedadas. O front matter do YAML configura a habilidade hospedada, e o corpo markdown torna-se as instruções. O teu projeto deve ter pelo menos um .agent.md ficheiro.
agents.config.yaml (Opcional) Define as predefinições de runtime para toda a aplicação, como o modelo, o timeout e as definições da sandbox.
mcp.json Define os servidores HTTP MCP remotos que as competências alojadas podem usar como ferramentas, incluindo ferramentas de ligação para ações como enviar emails ou trabalhar com o Teams.
tools/ (Opcional) Contém quaisquer ferramentas Python personalizadas que crie para fornecer capacidades que não sejam já fornecidas por servidores MCP, ligações, competências ou execuções em sandbox.
skills/ (Opcional) Contém recursos de prompt reutilizáveis SKILL.md que as competências alojadas podem carregar conforme necessário.

Cada ficheiro .agent.md utiliza um cabeçalho YAML seguido de instruções em Markdown. Este exemplo define uma habilidade hospedada ativada por temporizador que corre diariamente às 15h (UTC):

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

A matéria inicial declara como a habilidade hospedada é invocada. O corpo em Markdown é o bloco de instruções que o ambiente de execução passa ao modelo durante a execução. A substituição de variáveis de ambiente permite que instruções e valores de configuração referenciam definições de aplicação, como $TO_EMAIL.

Cada .agent.md ficheiro define uma competência alojada. O nome do ficheiro determina o nome da Azure Function e o segmento de rota dos pontos finais incorporados. O name campo é um nome de exibição para registos, etiquetas e documentação.

Para a lista completa dos campos do ficheiro .agent.md, das opções de configuração da aplicação e das regras de substituição de variáveis, consulte a referência das competências alojadas no Funções do Azure.

Crie e teste com o canvas de competências alojado

Como parte da pré-visualização de hosted skills, o Funções do Azure disponibiliza um canvas opcional de hosted skills no GitHub Copilot. O canvas é uma superfície interativa onde o utilizador e o GitHub Copilot podem criar uma aplicação inicial, escolher controlos de eventos Timer, HTTP ou Queue, editar as instruções da skill, selecionar um modelo compatível, iniciar o host local de Funções, invocar o gatilho e inspecionar a atividade e o resultado.

A partir do canvas, podes abrir o projeto gerado no Visual Studio Code ou usar a ação integrada Deploy to Azure. A ação de implementação utiliza a Azure Developer CLI (azd).

O canvas orienta e visualiza o fluxo de trabalho de desenvolvimento, mas não substitui o runtime de skills alojadas ou o formato do projeto. Uma aplicação criada através do canvas mantém-se como uma aplicação padrão de funções Python v2 que utiliza os ficheiros do projeto de competências alojados. Pode continuar a editar, executar e publicar a aplicação fora do canvas.

O quickstart do canvas foca-se em criar, executar e inspecionar uma habilidade local hospedada ativada por temporizador. Para o fluxo de trabalho guiado, consulte Criar e testar uma skill alojada com a estrutura de tópicos de skills alojadas no Funções do Azure.

Processo de arranque da aplicação

Quando o anfitrião do Functions carrega a aplicação, o método create_function_app deteta ficheiros .agent.md, servidores MCP, capacidades e ferramentas personalizadas no projeto. Valida a configuração, reúne as ferramentas para cada competência hospedada e regista os gatilhos e endpoints necessários.

Quando um gatilho dispara, o runtime constrói a habilidade hospedada com as suas instruções resolvidas, modelo, ferramentas e histórico de sessão, e depois executa-a.

Habilidades hospedadas pelo Trigger a partir de eventos

O runtime suporta múltiplos gatilhos na tua aplicação, mas apenas um gatilho por ficheiro .agent.md. Uma definição de gatilho tem um type e um args objeto. O type identifica a associação do acionador, e args contém as definições específicas do acionador que configuram qual o evento que inicia a competência alojada.

Padrões comuns de gatilho incluem:

Padrão Exemplo
HTTP Receber uma solicitação, invocar ferramentas e devolver uma resposta estruturada.
Horário Execute um fluxo de trabalho diário de criação de relatórios, resumo, limpeza ou reconciliação.
Fila ou mensagem Processar itens de trabalho que necessitem de raciocínio de modelo ou chamadas de ferramentas.
Evento de armazenamento ou base de dados Reagir a ficheiros, registos ou eventos alterados.
Gatilho de ligação Reagir a eventos de conectores geridos, como mensagens do Teams, correio do Outlook ou eventos de calendário suportados pelo conector.

Para obter detalhes sobre a configuração de acionadores, os tipos suportados e a args referência, consulte a referência de competências alojadas no Funções do Azure.

Ferramentas de IA suportadas

As competências alojadas do Funções do Azure suportam vários tipos de ferramentas. Começa com capacidades configuradas e usa ferramentas Python personalizadas para lógica específica da aplicação que não se encaixe nessas opções.

Servidores MCP remotos

Defina servidores HTTP remotos ou HTTP MCP transmitíveis em mcp.json. O ambiente de execução descobre estes servidores e disponibiliza as suas ferramentas a todas as capacidades alojadas. Utilize servidores MCP remotos quando as competências alojadas precisarem de invocar ferramentas alojadas noutro serviço ou combinar capacidades entre aplicações.

Conectores do Azure

Os conectores permitem que competências alojadas trabalhem com serviços externos sem código cliente API personalizado. Um Espaço de nomes do conector acolhe conexões, acionadores e servidores MCP para serviços como o Microsoft 365 Outlook, o Teams, o Salesforce, o SAP ou o SQL. Utilize gatilhos do conetor para iniciar competências alojadas a partir de eventos externos e ferramentas MCP do conetor para invocar ações de serviço a partir de instruções de competências alojadas.

Competências

Guarde os recursos de prompt reutilizáveis na pasta skills/. Cada pasta de habilidades contém um SKILL.md ficheiro com um nome, descrição e instruções de marcação. O runtime descobre automaticamente as competências e torna-as disponíveis para as competências alojadas. As competências ajudam a manter as instruções base pequenas, ao mesmo tempo que disponibilizam orientações específicas para cada domínio quando necessário.

Execução em sandbox

O runtime pode usar sessões dinâmicas do Azure Container Apps para fornecer às competências hospedadas uma ferramenta execute_python. Esta ferramenta executa Python num pool de sessões isolado, o que é útil para execução de código e análise de dados. Configure o ponto final do pool de sessões em agents.config.yaml.

Ferramentas personalizadas de Python

Usa ferramentas Python personalizadas para capacidades específicas da aplicação. Adicione ficheiros .py à pasta tools/ e decore funções com @tool do pacote de runtime. O runtime descobre e regista automaticamente estas ferramentas.

Para detalhes de configuração, tabelas de campos e exemplos de código para cada tipo de ferramenta, consulte a referência de competências hospedadas no Funções do Azure.

Fluxos de trabalho dinâmicos

Os fluxos de trabalho dinâmicos permitem que tarefas de IA suportadas iniciem planos persistentes com várias etapas, compostos por chamadas a ferramentas compatíveis com fluxos de trabalho, tarefas de subagentes e períodos de espera. Eles expandem o padrão de chamada programática de ferramentas com o Durable Functions, para que uma tarefa possa distribuir o trabalho, executar especialistas isolados, esperar por temporizadores persistentes, sobreviver a reinícios de processos de trabalho e manter resultados intermédios volumosos fora da conversa até que um resumo final esteja pronto.

Na superfície experimental v1 atual, permita fluxos de trabalho num ficheiro executável .agent.md de forma independente. As tarefas do fluxo de trabalho podem chamar funções Python que decora explicitamente com @workflow_tool ou tarefas especializadas que concede através de workflows.subagents. Para mais informações, consulte Fluxos de trabalho dinâmicos nas competências alojadas no Funções do Azure.

Sessões e estado

As interações com vários turnos precisam de histórico de sessões. No Azure, o tempo de execução armazena o histórico de sessões no Armazenamento de Blobs na conta da aplicação de funções AzureWebJobsStorage. Para desenvolvimento local, o runtime recorre ao histórico de sessões baseado em ficheiros. A execução em sandbox tem também em conta a sessão e utiliza sessões isoladas para execuções não relacionadas.

Observability

A partir da azure-functions-agents-runtime versão 0.1.0b6, o runtime inclui um conjunto de funcionalidades de observabilidade que ainda está em desenvolvimento ativo e sujeito a alterações.

Para os detalhes de configuração mais recentes, campos de telemetria e orientações de utilização, utilize a documentação do repositório em tempo de execução:

Para configuração da monitorização, consultas KQL, utilização de tokens, latência e verificações de conectores, consulte Monitorizar e resolver problemas de competências alojadas.

Conteúdo relacionado

  • Última atualização a