Partilhar via

Registrar e gerenciar agentes personalizados

O Microsoft Foundry Control Plane proporciona gestão centralizada e observabilidade para agentes que correm em diferentes plataformas e infraestruturas. Pode registar agentes personalizados que correm em serviços de computação Azure ou outros ambientes cloud para obter visibilidade das suas operações e controlar o seu comportamento.

Este artigo mostra-lhe como registar um agente personalizado na Foundry Control Plane. Aprende a configurar o seu agente para o registo, a configurar a recolha de dados e a usar as capacidades de gestão do Foundry Control Plane.

Pré-requisitos

  • Um gateway de IA configurado no seu recurso Foundry. O Foundry utiliza o Azure API Management para registar agentes como APIs.

  • Um agente que implementas e expões através de um endpoint acessível. O endpoint pode ser um endpoint público ou um endpoint acessível a partir da rede onde implementas o recurso Foundry.

Observação

Esta funcionalidade está disponível apenas no portal Foundry (novo). Procura no banner do portal para confirmar que estás a usar o Foundry (novo).

Adicionar um agente personalizado

Pode registar um agente personalizado na Foundry Control Plane. Desenvolva o agente na tecnologia que preferir, tanto para soluções de plataforma como de infraestrutura.

Quando regista um agente personalizado, a Foundry utiliza a API Management para atuar como um proxy das comunicações com o seu agente, para poder controlar o acesso e monitorizar a atividade.

O diagrama seguinte mostra a arquitetura resultante quando regista um agente personalizado.

Diagrama que mostra a arquitetura resultante após o registo e configuração de um agente personalizado.

Verifique o seu agente

Verifique se seu agente atende aos requisitos para registro:

  • O seu agente expõe um endpoint exclusivo.
  • A rede onde implementas o recurso Foundry pode chegar ao endpoint do agente.
  • O agente comunica utilizando um dos protocolos suportados: HTTP (geral) ou A2A (mais específico).
  • O seu agente emite dados usando as convenções semânticas da OpenTelemetry para soluções de IA generativa (ou então não precisa desta capacidade).
  • Pode configurar o endpoint que os utilizadores usam para comunicar com o agente. Depois de registar um agente, o Foundry Control Plane gera uma nova URL. Clientes e utilizadores devem usar esta URL para comunicar com o agente.

Prepare o seu projeto Foundry

Antes de registares o agente personalizado que adicionaste a um projeto Foundry, certifica-te de que configuraste o projeto corretamente:

  1. Inicie sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se ao Foundry (novo).

  2. Certifique-se de que um gateway de IA está configurado no seu projeto:

    1. Na barra de ferramentas, selecione Operar.

    2. No painel esquerdo, selecione Administrador.

    3. Abra o separador AI Gateway.

    4. O painel lista todos os gateways de IA configurados e mapeados para um recurso Foundry. Verifica se o recurso do Foundry que queres usar tem um gateway de IA associado.

      Captura de ecrã do portal de administração da Foundry que mostra os passos para verificar se um projeto tem um gateway de IA configurado.

    5. Se o recurso da Foundry que pretende usar não tiver um gateway de IA configurado (não está listado), adicione um usando a opção Adicionar Gateway de IA .

      Um gateway de IA é gratuito para configurar e desbloquear funcionalidades poderosas de governação como segurança, dados de diagnóstico e limites de taxa para os seus agentes, ferramentas e modelos. Para mais informações, consulte Criar um gateway de IA.

  3. Certifique-se de que tem a observabilidade configurada no projeto. O Foundry Control Plane utiliza o recurso Application Insights associado ao projeto selecionado para emitir dados que o ajudem a diagnosticar o seu agente.

    1. Na barra de ferramentas, selecione Operar.

    2. No painel esquerdo, selecione Administrador.

    3. Em Todos os projetos, use a caixa de pesquisa para procurar o seu projeto.

    4. Seleciona o projeto.

    5. Selecione o separador Recursos Conectados .

    6. Certifique-se de que existe um recurso associado na categoria AppInsights .

      Captura de ecrã do portal de administração que mostra os passos para verificar se um projeto tem um recurso de Application Insights associado.

    7. Se não houver um recurso associado, adicione um selecionando Adicionar ligação>Application Insights.

O seu projeto está configurado para observabilidade e rastreamento.

Registar o agente

  1. Na barra de ferramentas, selecione Operar.

  2. No painel Visão geral , selecione Registrar agente.

    Captura de ecrã do botão para registar um agente no painel de Visão Geral do portal Foundry.

  3. O assistente de registro aparece. Primeiro, complete os detalhes sobre o agente que pretende registar. As seguintes propriedades descrevem o agente tal como este é executado na sua plataforma:

    Propriedade Description Obrigatório
    URL do agente O endpoint (URL) onde o seu agente corre e recebe pedidos. Em geral, mas dependendo do seu protocolo, você indica a URL base que seus clientes usam. Por exemplo, se o seu agente usa a API OpenAI Chat Completions, deverá indicar https://<host>/v1/ sem /chat/completions porque, geralmente, os clientes a adicionam. Yes
    Protocol O protocolo de comunicação que o seu agente suporta. Usa HTTP em geral. Ou, se o seu agente apoia o A2A de forma mais específica, indique esse ponto. Yes
    URL do cartão de agente A2A O caminho para a especificação JSON do cartão do agente. Se não o especificar, o sistema usa o valor padrão /.well-known/agent-card.json. Não
    ID do agente OpenTelemetry O ID do agente que o seu agente usa para emitir traços de acordo com as convenções semânticas da OpenTelemetry para IA generativa. Os traços estão indicados no atributo gen_ai.agents.id para intervalos com o nome create_agent da operação. Se não especificar este valor, o sistema usa o valor do nome do Agente para encontrar vestígios e registos que este novo agente reporta. Não
    URL do portal de administração A URL do portal de administração onde você pode executar outras operações de administração para esse agente. A fundição pode armazenar este valor por conveniência. A Foundry não tem acesso para realizar operações diretamente neste portal. Não

  4. Configure como quer que o agente apareça no Foundry Control Plane:

    Propriedade Description Obrigatório
    Projeto O projeto onde você registra o agente. O Foundry utiliza o gateway de IA configurado no recurso que contém o projeto para configurar o endpoint de entrada para o agente. Só pode selecionar projetos que tenham um gateway de IA ativado nos seus recursos. Se não vires nenhum gateway de IA, configura um gateway de IA no teu recurso Foundry. Recomendamos também que configure o Application Insights no projeto selecionado. A Foundry utiliza o recurso Application Insights do projeto para encaminhar rastros e registos. Yes
    Nome do agente O nome do agente, tal como queres que apareça na Foundry. O sistema pode também usar este nome para encontrar vestígios e registos relevantes no Application Insights se não especificar um valor diferente para o OpenTelemetry Agent ID. Yes
    Descrição Uma descrição clara sobre este agente. Não

  5. Salve as alterações.

  6. Foundry adiciona o novo agente. Para verificar a lista de agentes, selecione Assets no painel esquerdo.

  7. Para mostrar apenas agentes personalizados, use o filtro Fonte e selecione Personalizado.

    Captura de ecrã de um agente aduaneiro registado.

Liga os clientes ao agente

Quando regista o seu agente na Foundry, recebe um novo URL para os seus clientes usarem. Como o Foundry atua como um proxy para as comunicações com o seu agente, pode controlar o acesso e monitorizar a atividade.

Para distribuir o novo URL para que os seus clientes possam ligar para o agente:

  1. Selecione o agente personalizado.

  2. No painel de detalhes, em URL do Agente, selecione a opção Copiar .

    Captura de ecrã dos passos para copiar o novo URL do agente após o registo.

  3. Use o novo URL para chamar o agente em vez do endpoint original.

Neste exemplo, implementas um agente LangGraph. Os clientes usam o SDK LangGraph para o consumir. O cliente utiliza o novo valor da URL do agente . Esse código cria um thread, envia uma mensagem perguntando sobre o clima e transmite a resposta de volta.

from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/") 

async def stream_run():
   thread = await client.threads.create()
   input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}
   
   async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
       print(chunk)

Saída esperada: o agente processa a mensagem e transmite as respostas como partes. Cada bloco contém resultados parciais da execução do agente. Estes resultados podem incluir chamadas de ferramentas para a função meteorológica e a resposta final sobre o tempo de Los Angeles.

Observação

Embora o Foundry atue como um proxy para pedidos recebidos do seu agente, o esquema original de autorização e autenticação no endpoint original ainda se aplica. Quando consumir o novo endpoint, forneça o mesmo mecanismo de autenticação que se estivesse a usar o endpoint original.

Bloqueia e desbloqueia o agente

Para agentes personalizados, o Foundry não tem acesso à infraestrutura subjacente onde o agente é executado, por isso as operações de início e paragem não estão disponíveis. No entanto, a Foundry pode bloquear pedidos recebidos ao agente para que os clientes não os possam consumir. Esse recurso permite que os administradores desativem um agente se ele se comportar mal.

Para bloquear solicitações de entrada ao seu agente:

  1. Na barra de ferramentas, selecione Operar.

  2. No painel esquerdo, selecione Ativos.

  3. Selecione o agente que quer bloquear. O painel de informação aparece.

  4. Selecione Atualizar estado e depois selecionar Bloquear.

    Captura de ecrã dos passos para bloquear pedidos recebidos a um agente.

  5. Confirme a operação.

Depois de bloqueares o agente, o valor de Estado do agente na Foundry é Bloqueado. Os agentes no estado Bloqueado são executados em sua infraestrutura associada, mas não podem receber solicitações de entrada. O Foundry bloqueia qualquer tentativa de interface com o agente.

Para desbloquear o agente:

  1. Seleciona Atualizar estado e depois seleciona Desbloquear.

  2. Confirme a operação.

Ativar dados de diagnóstico para o agente

A Foundry utiliza o padrão aberto OpenTelemetry para perceber o que os agentes estão a fazer. Se o seu projeto tiver o Application Insights configurado, o Foundry regista pedidos no Application Insights por defeito. A Foundry também utiliza estes dados para calcular:

  • Runs
  • Taxa de erro
  • Utilização (se disponível)

Para obter o melhor nível de fidelidade, a Foundry espera que os agentes personalizados cumpram as convenções semânticas para soluções de IA generativa no padrão OpenTelemetry.

Ver rastros e logs enviados para a Foundry

  1. Na barra de ferramentas, selecione Operar.

  2. No painel esquerdo, selecione Ativos.

  3. Selecione o agente.

  4. A secção Traces mostra uma entrada para cada chamada HTTP feita ao endpoint do agente.

    Para ver os detalhes, selecione uma entrada.

    Captura de ecrã de uma chamada para o endpoint do agente sob a rota para runs e streams.

    Sugestão

    Neste exemplo, pode ver como os clientes usam o endpoint do novo agente para comunicar com ele. O exemplo mostra um agente servido com o Protocolo de Agente do LangChain. Os clientes utilizam a rota /runs/stream.

Neste exemplo, o rastreio não inclui detalhes para além do post HTTP. O código do agente não inclui qualquer instrumentação adicional. Na secção seguinte, aprendes a instrumentar o teu código e obténs detalhes como chamadas de ferramentas e chamadas a grandes modelos de linguagem (LLM).

Implementar agentes de código personalizado

Se construir o seu agente usando código personalizado, instrumente a sua solução para emitir traços de acordo com o padrão OpenTelemetry e envie-os para o Application Insights. A instrumentação dá à Foundry acesso a informações detalhadas sobre o que o seu agente está a fazer.

Envie traços para o recurso Application Insights do seu projeto usando a sua chave de instrumentação. Para obter a chave de instrumentação associada ao seu projeto, siga as instruções em Ativar rastreamento em seu projeto.

Neste exemplo, você configura um agente desenvolvido com LangGraph para emitir rastreamentos no padrão OpenTelemetry . O rastreador capta todas as operações do agente, incluindo invocações de ferramentas e interações com modelos. O rastreador envia então as operações para o Application Insights para monitorização.

Este código utiliza o pacote langchain-azure-ai . Para orientações sobre instrumentação de soluções específicas com OpenTelemetry, dependendo da linguagem de programação e do framework que a sua solução utiliza, consulte APIs e SDKs da Linguagem.

pip install -U langchain-azure-ai[opentelemetry]

Depois, configure o seu agente:

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = 'InstrumentationKey="12345678...'

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

Saída esperada: O agente funciona normalmente enquanto emite automaticamente traços OpenTelemetry para Application Insights. Os rastreamentos incluem nomes de operações, durações, chamadas de modelos, invocações de ferramentas e utilização de tokens. Pode ver estes vestígios no portal da Foundry, na secção Traces .

Sugestão

Pode passar a cadeia de ligação ao Application Insights usando a variável de ambiente APPLICATIONINSIGHTS_CONNECTION_STRING.

Soluções de plataforma de instrumentos

Se o seu agente corre numa solução de plataforma que suporta OpenTelemetry mas não suporta Application Insights, implemente um coletor OpenTelemetry e configure o seu software para enviar dados OTLP para o coletor (configuração padrão OpenTelemetry).

Configure o coletor com o exportador Azure Monitor para encaminhar dados para o Application Insights usando a sua cadeia de ligação. Para detalhes sobre como implementá-lo, consulte Configurar Azure Monitor OpenTelemetry.

Rastreios de resolução de problemas

Se não encontrar rastos, verifique os seguintes itens:

  • O projeto onde regista o seu agente tem o Application Insights configurado. Se configurou o Application Insights depois de registar o agente personalizado, precisa de anular o registo do agente e voltar a registá-lo. A configuração do Application Insights não é atualizada automaticamente após o registo se a alteraste.
  • Configuraste o agente (a correr na sua infraestrutura) para enviar traços para o Application Insights e estás a usar o mesmo recurso do Application Insights que o teu projeto utiliza.
  • Instrumentação cumpre as convenções semânticas da OpenTelemetry para IA generativa.
  • Os traces incluem spans com atributos operation="create_agent" e gen_ai.agents.id="<agent-id>" (ou gen_ai.agents.name="<agent-id>"). Neste último atributo, "<agent-id>" está o valor do ID do Agente OpenTelemetry que configurou durante o registo.

Conteúdo relacionado

  • Last updated on