Registrar e gerenciar agentes personalizados

O Plano de Controle do Microsoft Foundry fornece gerenciamento centralizado e observabilidade para agentes em execução em diferentes plataformas e infraestruturas. Você pode registrar agentes personalizados — em execução nos serviços de computação do Azure ou em outros ambientes de nuvem — para obter visibilidade de suas operações e controlar seu comportamento.

Este artigo mostra como registrar um agente personalizado no Plano de Controle do Foundry. Você aprenderá a configurar seu agente para registro, configurar a coleção de telemetria e usar os recursos de gerenciamento do Plano de Controle.

Pré-requisitos

Antes de começar, verifique se você tem:

• 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 do Foundry. Se você não tiver um, crie um projeto.

• A Foundry usa o Gerenciamento de API do Azure para registrar agentes como APIs. Configure o Gateway de IA em seu recurso do Foundry.

• Um agente que você implanta e expõe por meio de um ponto de extremidade acessível (um ponto de extremidade público ou um ponto de extremidade acessível a partir da rede onde você implanta o recurso Foundry).

Adicionar um agente personalizado

Você pode registrar um agente personalizado no Plano de Controle. Desenvolva o agente na tecnologia de sua escolha, tanto soluções de plataforma quanto de infraestrutura.

Quando você registra um agente personalizado, o Foundry usa o Gerenciamento de API do Azure para atuar como um proxy para comunicações com seu agente, para que ele possa controlar o acesso e monitorar a atividade.

Quando você registra um agente personalizado, a arquitetura resultante é a seguinte:

Verifique seu agente

Verifique se o agente atende aos requisitos de registro:

Preparar seu projeto do Foundry

Agentes personalizados são adicionados a projetos do Foundry. Antes de registrar o agente, vamos verificar se você configurou o projeto corretamente.

1. Entrar no Microsoft Foundry. Certifique-se de que a chave New Foundry está ativada. Estas etapas referem-se à Fábrica (novo).

   

2. Verifique se o Gateway de IA está configurado em seu projeto:

   1. Selecione Operar>console do Administrador.

   2. Abra a aba Gateway de IA.

   3. A página lista todos os Gateways de IA configurados e mapeados para um recurso do Foundry. Verifique se o recurso Foundry que você deseja usar tem um Gateway de IA associado.

      

   4. Se o recurso Foundry que você deseja usar não tiver um Gateway de IA configurado (ele não está listado), adicione um usando a opção Adicionar Gateway de IA. O Gateway de IA é gratuito para configurar e desbloqueia recursos de governança avançados, como segurança, telemetria e limites de taxa para seus agentes, ferramentas e modelos.

   5. Para obter mais detalhes sobre como configurar o Gateway de IA, consulte Criar um Gateway de IA.

3. Verifique se você tem a observabilidade configurada no projeto. O Plano de Controle usa o recurso do Azure Application Insights associado ao projeto selecionado para emitir telemetria para ajudá-lo a diagnosticar seu agente:

   1. Selecione Operar>console do Administrador.

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

   3. Selecione o projeto.

   4. Selecione a guia Recursos conectados.

   5. Verifique se há um recurso associado na categoria Application Insights.

      

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

   7. Seu projeto está configurado para observação e rastreamento.

Registrar o agente

Para registrar o agente, siga estas etapas:

1. Selecione Operar na navegação superior direita.

2. Selecione o painel Visão Geral .

3. Selecione Agente de Registro.

   

4. O assistente de registro é exibido. Primeiro, conclua os detalhes sobre o agente que você deseja registrar. As propriedades a seguir descrevem o agente como ele é executado em sua plataforma

   Propriedade	Description	Obrigatório
   URL do agente	Ele representa o endpoint (URL) onde o seu agente opera e recebe solicitações. Em geral, mas dependendo do protocolo, você indica a URL base que seus clientes usam. Por exemplo, se o seu agente utiliza a API de Conclusões de Chat do OpenAI, você indica https://<host>/v1/ - sem /chat/completions, pois os clientes geralmente a adicionam.	Yes
   Protocolo	O protocolo de comunicação suportado pelo agente. Use HTTP em geral ou, se o agente oferecer suporte a A2A de forma mais específica, indique isso.	Yes
   URL do cartão do agente A2A	Caminho para a especificação JSON do cartão do agente. Se você não especificá-lo, o sistema usará o padrão /.well-known/agent-card.json.	Não
   OpenTelemetry Agent ID	A ID do Agente que seu agente usa para emitir rastreamentos de acordo com as convenções semânticas de IA generativa do OpenTelemetry. Os rastreamentos indicam isso no atributo gen_ai.agents.id para intervalos com o nome de operação create_agent. Se você não especificar isso, o sistema usará o valor do nome do Agente para localizar rastreamentos e logs que esse novo agente relata.	Não
   URL do portal de administração	A URL do portal de administração em que você pode executar outras operações de administração para esse agente. A Foundry pode armazenar esse valor para facilitar a conveniência de acesso. A Foundry não tem acesso para executar operações diretamente nesse portal de gerenciamento.	Não

5. Em seguida, configure como você deseja que o agente apareça no Painel de Controle:

   Propriedade	Description	Obrigatório
   Projeto	O projeto em que você registra o agente. A Foundry usa o Gateway de IA configurado no recurso em que o projeto reside para configurar o endpoint de entrada para o agente. Você só pode selecionar projetos com o Gateway de IA habilitado em seus recursos. Se você não vir nenhum, configure o Gateway de IA no seu recurso Foundry. Também é aconselhável configurar o Azure Application Insights no projeto selecionado. O Foundry usa o recurso do Azure Application Insights do projeto para coletar rastreamentos e logs.	Yes
   Nome do agente	O nome do agente como você deseja que ele apareça no Foundry. O sistema também poderá usar esse nome para localizar rastreamentos e logs relevantes no Azure Application Insights, caso você não especifique um valor diferente no campo ID do Agente OpenTelemetry.	Yes
   Descrição	Uma descrição clara sobre este agente.	Não

6. Salve as alterações.

7. A Foundry adiciona o novo agente. Selecione a guia Ativos no painel esquerdo para verificar a lista de agentes.

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

   

Conectar clientes ao agente

Ao registrar seu agente no Foundry, você obtém uma nova URL para seus clientes usarem. A foundry atua como um proxy para comunicações com seu agente, para que possa controlar o acesso e monitorar a atividade.

Para distribuir a nova URL para seus clientes chamarem o agente:

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

2. No painel de detalhes à direita, na URL do Agente, selecione a opção de cópia.

   

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

Neste exemplo, você implanta um agente do LangGraph e os clientes usam o SDK do LangGraph para consumi-lo. O cliente usa o novo valor de 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 respostas de volta como partes. Cada bloco contém resultados parciais da execução do agente, que podem incluir chamadas de ferramenta para a função meteorológica e a resposta final sobre o clima de Los Angeles.

Bloquear e desbloquear o agente

No caso de agentes personalizados, a Foundry não tem acesso à infraestrutura subjacente em que o agente é executado, portanto, as operações de inicialização e parada não estão disponíveis. No entanto, a Foundry pode bloquear solicitações de entrada para o agente, impedindo que os clientes consumam o serviço. Essa funcionalidade permite que os administradores desabilitem um agente se ele se comportar mal.

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

1. Selecione Operar na navegação superior direita.

2. Selecione Ativos no painel esquerdo.

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

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

   

5. Confirme a operação.

Depois de bloquear o agente, o Status do agente na Foundry é mostrado como Bloqueado. Os agentes no estado Bloqueado são executados em sua infraestrutura associada, mas não podem receber solicitações de entrada. Uma fundição bloqueia qualquer tentativa de interagir com o agente.

Para desbloquear o agente:

1. Selecione Atualizar status e, em seguida, selecione Desbloquear.

2. Confirme a operação.

Habilitar a telemetria para seu agente

A Foundry usa o padrão aberto OpenTelemetry para entender o que os agentes estão fazendo. Se o projeto tiver o Azure Application Insights configurado, o Foundry registrará solicitações no Azure Application Insights por padrão. Essa telemetria também é usada para calcular:

• Runs
• Taxa de erros
• Uso (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.

Exibir execuções e rastreamentos

Você pode visualizar rastreamentos e logs enviados para Foundry. Para exibi-los:

1. Selecione Operar na navegação superior direita.

2. Selecione Ativos no painel esquerdo.

3. Selecione o agente.

4. As seções de rastreamento são exibidas.

5. Você vê uma entrada para cada requisição HTTP feita no endpoint do agente.

6. Para ver os detalhes, selecione uma entrada:

   

   Dica

   Neste exemplo, você pode ver como os clientes usam o endpoint do novo agente para se comunicarem com o agente. O exemplo mostra um agente servido com o Protocolo do Agente do LangChain. Os clientes usam a rota /runs/stream.

7. Observe neste exemplo que não há mais detalhes além da postagem HTTP no rastreamento. Isso ocorre porque nenhuma instrumentação adicional foi adicionada ao código do agente. Consulte a próxima seção para saber como instrumentar seu código e obter mais detalhes, como chamadas de ferramenta, chamadas LLM etc.

Instrumentar agentes de código personalizados

Se você criar seu agente com código personalizado, precisará instrumentar sua solução para emitir rastros de acordo com o padrão OpenTelemetry e enviá-los ao Azure Application Insights. A instrumentação permite que o Foundry tenha acesso a um nível mais alto de detalhes sobre o que seu agente está fazendo.

Envie rastreamentos para o recurso do 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 Habilitar rastreamento em seu projeto.

Neste exemplo, você configura um agente desenvolvido com o LangGraph para emitir rastreamentos no padrão OpenTelemetry. O rastreador captura todas as operações do agente, incluindo chamadas de ferramenta e interações de modelo, e as envia ao Azure Application Insights para monitoramento.

Esse código usa o pacote langchain-azure-ai . Saiba como instrumentar soluções específicas com o OpenTelemetry, dependendo da linguagem de programação e da estrutura usada em sua solução em APIs de Linguagem &SDKs..

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

Em seguida, instrumente 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 no Azure Application Insights. Os rastreamentos incluem nomes de operação, durações, chamadas de modelo, invocações de ferramenta e uso de tokens. Você pode exibir esses rastreamentos no portal do Foundry na seção Rastreamentos.

Soluções de plataforma de instrumentação

Se o agente for executado em uma solução de plataforma que dê suporte ao OpenTelemetry, mas não der suporte ao Azure Application Insights, você precisará implantar um Coletor OpenTelemetry e configurar seu software para enviar dados OTLP para o Coletor (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 OpenTelemetry do Azure Monitor.

Solucionando problemas de rastreamentos

Se você não vir rastros, verifique o seguinte:

Conteúdo relacionado

• O que é o Plano de Controle do Microsoft Foundry?
• Monitorar agentes em toda a sua frota
• Otimizar o custo e o desempenho em toda a frota de agentes