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 — a correr em serviços de computação Azure ou noutros ambientes cloud — para obter visibilidade sobre as suas operações e controlar o seu comportamento.

Este artigo mostra-lhe como registar um agente alfandegário no Plano de Controlo da Fundição. Aprende a configurar o seu agente para o registo, configurar a recolha de telemetria e usar as capacidades de gestão do Plano de Controlo.

Pré-requisitos

Antes de começar, certifique-se de que:

• Uma conta do Azure com uma assinatura ativa. Se você não tiver uma, crie uma conta gratuita do Azure, que inclui uma assinatura de avaliação gratuita.

• Um projeto da Foundry. Se você não tiver um, crie um projeto.

• O Foundry utiliza o Azure API Management para registar agentes como APIs. Configure o AI Gateway no seu recurso Foundry.

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

Adicionar um agente personalizado

Pode registar um agente personalizado no Plano de Controlo. Desenvolva o agente na tecnologia da sua escolha, tanto soluções de plataforma como de infraestrutura.

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

Quando regista um agente personalizado, a arquitetura resultante é a seguinte:

Verifique o seu agente

Verifique se seu agente atende aos requisitos para registro:

Prepare o seu projeto Foundry

Agentes alfandegários são adicionados aos projetos da Foundry. Antes de registar o agente, vamos garantir que configurou 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. Garanta que o AI Gateway está configurado no seu projeto:

   1. Selecione Operar>Admin Console.

   2. Abra o separador AI Gateway.

   3. A página lista todos os Gateways de IA configurados e mapeados para um recurso Foundry. Verifica se o recurso do Foundry que queres usar tem um AI Gateway associado.

      

   4. Se o recurso Foundry que queres usar não tiver um Gateway de IA configurado (não está listado), adiciona um usando a opção Adicionar Gateway de IA. O AI Gateway é gratuito para configurar e desbloquear funcionalidades poderosas de governação, como segurança, telemetria e limites de taxa para os seus agentes, ferramentas e modelos.

   5. Para mais detalhes sobre como configurar o AI Gateway, consulte Criar um AI Gateway.

3. Certifique-se de que tem a observabilidade configurada no projeto. O Control Plane utiliza o recurso Azure Application Insights associado ao projeto selecionado para emitir telemetria e ajudar a diagnosticar o seu agente:

   1. Selecione Operar>Admin Console.

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

   3. Seleciona o projeto.

   4. Selecione o separador Recursos Conectados.

   5. Assegure que existe um recurso associado sob a categoria Application Insights.

      

   6. Se não houver nenhum recurso associado, adicione um selecionando Adicionar ligação e selecione Application Insights.

   7. O seu projeto está configurado para observabilidade e rastreamento.

Registar o agente

Para registar o agente, siga os seguintes passos:

1. Selecione Operar na navegação no canto superior direito.

2. Selecione o painel de Visão Geral .

3. Selecione Registar agente.

   

4. O assistente de registro aparece. Primeiro, preencha os detalhes sobre o agente que você deseja registrar. As propriedades a seguir descrevem o agente à medida que ele é executado em sua plataforma:

   Propriedade	Description	Obrigatório
   URL do agente	Ele representa o ponto de extremidade (URL) onde seu agente é executado e recebe solicitações. Em geral, mas dependendo do seu protocolo, você indica a URL base que seus clientes usam. Por exemplo, se o seu agente utiliza ou suporta a API OpenAI Chat Completions, você indica https://<host>/v1/ - sem /chat/completions porque os clientes geralmente o adicionam.	Yes
   Protocol	O protocolo de comunicação suportado pelo seu agente. Use HTTP em geral ou, se o seu agente suportar mais especificamente A2A, indique esse.	Yes
   URL do cartão de agente A2A	Caminho para a especificação JSON do cartão de 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 de Agente que o seu agente usa para emitir rastros de acordo com as convenções semânticas OpenTelemetry Generative AI. Os rastreamentos indicam isso no atributo gen_ai.agents.id para spans com nome de operação create_agent. Se você não especificar isso, o sistema usará o valor Nome do agente para localizar rastreamentos e logs relatados por esse novo agente.	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 para facilitar o acesso. A Foundry não tem acesso direto para realizar operações nesse portal de gestão.	Não

5. Depois, configura como queres que o agente apareça no Plano de Controlo:

   Propriedade	Description	Obrigatório
   Projeto	O projeto onde você registra o agente. Foundry utiliza o AI Gateway configurado no recurso onde o projeto reside para configurar o endpoint de entrada para o agente. Você só pode selecionar projetos com o AI Gateway ativado em seus recursos. Se não vires nenhum, configura o AI Gateway no teu recurso Foundry. Também é aconselhável configurar o Azure Application Insights no projeto selecionado. A Foundry utiliza o recurso Azure Application Insights do projeto para registar rastreios e logs.	Yes
   Nome do agente	O nome do agente, tal como queres que apareça na Foundry. O sistema também pode usar esse nome para localizar rastreamentos e logs relevantes no Azure Application Insights se você não especificar um valor diferente no campo OpenTelemetry Agent ID.	Yes
   Descrição	Uma descrição clara sobre este agente.	Não

6. Salve as alterações.

7. Foundry adiciona o novo agente. Selecione o separador Assets no painel esquerdo para verificar a lista de agentes.

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

   

Liga os clientes ao agente

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

Para distribuir a nova URL para que os seus clientes possam ligar ao agente:

1. Selecione o agente personalizado usando o seletor de rádio.

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

   

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

Neste exemplo, você implanta um agente LangGraph e os clientes usam o SDK LangGraph para consumi-lo. 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 parte contém resultados parciais da execução do agente, que podem incluir chamadas de ferramentas para a função meteorológica e a resposta final sobre o clima de Los Angeles.

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, o Foundry pode bloquear solicitações recebidas pelo agente, impedindo que os clientes as consumam. Esse recurso permite que os administradores desativem um agente se ele se comportar mal.

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

1. Selecione Operar na navegação no canto superior direito.

2. Selecione Assets no painel esquerdo.

3. Selecione o agente que deseja bloquear. O painel de informações é exibido.

4. Selecione Atualizar estado e, em seguida, selecione Bloquear.

   

5. Confirme a operação.

Depois de bloqueares o agente, o estado do agente na Foundry aparece como 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. Selecione Atualizar estado e, em seguida, selecione Desbloquear.

2. Confirme a operação.

Habilite a telemetria para seu 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 Azure Application Insights configurado, o Foundry regista pedidos no Azure Application Insights por defeito. Esta telemetria também é usada 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 a solução de IA Generativa no padrão OpenTelemetry.

Ver execuções e rastreamentos

Pode ver os vestígios e registos enviados para a Foundry. Para os visualizar:

1. Selecione Operar na navegação no canto superior direito.

2. Selecione Assets no painel esquerdo.

3. Selecione o agente.

4. Aparecem secções de traços .

5. Vês uma entrada por cada chamada HTTP feita ao endpoint do agente.

6. Para ver os detalhes, selecione uma entrada:

   

   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.

7. Note neste exemplo que não há mais detalhes além do post HTTP presentes no rastreio. Isto deve-se ao facto de não ter sido adicionada mais instrumentação ao código do agente. Veja a secção seguinte para aprender como instrumentar o seu código e obter mais detalhes como chamadas de ferramentas, chamadas de LLM, etc.

Implementar agentes de código personalizado

Se você criar seu agente com código personalizado, precisará instrumentar sua solução para emitir rastreamentos de acordo com o padrão OpenTelemetry e coletá-los para o Azure Application Insights. A instrumentação permite à Foundry ter acesso a um nível de detalhe mais elevado sobre o que o seu agente está a fazer.

Envie rastreamentos para o recurso Azure Application Insights do seu projeto usando 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 captura todas as operações do agente, incluindo chamadas de ferramentas e interações de modelo, e as envia para o Azure Application Insights para monitoramento.

Este código utiliza o pacote langchain-azure-ai . Aprenda a instrumentar soluções específicas com OpenTelemetry dependendo da linguagem de programação e do framework usado na sua solução em Language APIs & SDKs..

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 é executado normalmente enquanto emite automaticamente rastreamentos OpenTelemetry para o Azure 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.

Soluções de plataforma de instrumentação

Se o seu agente for executado em uma solução de plataforma que ofereça suporte ao OpenTelemetry mas não ofereça suporte ao Azure Application Insights, você precisará implantar um OpenTelemetry Collector e configurar seu software para enviar dados OTLP para o Collector (configuração padrão do OpenTelemetry ).

Configure o Coletor com o exportador do Azure Monitor para encaminhar dados para o Application Insights usando sua cadeia de conexão. Para obter detalhes sobre como implementar, consulte Configurar o Azure Monitor OpenTelemetry.

Rastreamento de problemas

Se não vires vestígios, verifica o seguinte:

Conteúdo relacionado

• O que é o Microsoft Foundry Control Plane?
• Monitorize os agentes em toda a sua frota
• Otimize custos e desempenho em toda a sua frota de agentes