Registar e gerir agentes aduaneiros

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 computacionais do Azure ou noutros ambientes cloud para obter visibilidade das suas operações e controlar o seu comportamento.

Este artigo mostra-lhe como registar um agente personalizado em 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

• Uma conta no Azure com uma subscrição ativa. Se não tiveres uma, cria uma conta Azure free, que inclui uma subscrição de teste gratuita.

• Um projeto da Foundry. Se não tiveres um, cria um projeto.

• Um gateway de IA configurado no seu recurso Foundry. O Foundry utiliza o API Management do Azure 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.

Adicione um agente de alfândega

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.

Verifique o seu agente

Verifique se o seu agente cumpre os requisitos para o registo:

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. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se à Foundry (nova).

   

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

      

   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 .

      

   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 (ativo)

1. Na barra de ferramentas, selecione Operar.

2. No painel de Visão Geral, selecione Registar ativo.

   

3. O mago de registo 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	Descrição	Obrigatório
   URL do agente	O endpoint (URL) onde o seu agente corre e recebe pedidos. Em geral, mas dependendo do seu protocolo, indica o URL base que os seus clientes usam. Por exemplo, se o seu agente usa a API OpenAI Chat Completions, você indica https://<host>/v1/ sem /chat/completions uma vez que os clientes geralmente a adicionam.	Sim
   Protocolo	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.	Sim
   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 indicam-no no atributo gen_ai.agent.id para os intervalos que têm 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	O URL do portal de administração onde pode realizar operações de administração adicionais para este 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	Descrição	Obrigatório
   Project	O projeto onde registas o agente. Foundry utiliza o gateway de IA configurado no recurso que contém o projeto para configurar o ponto final 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 registar rastreios e registos.	Sim
   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.	Sim
   Descrição	Uma descrição clara sobre este agente.	Não

5. Guarda 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.

   

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 .

   

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 . Este código cria um tópico, envia uma mensagem a perguntar sobre o tempo e transmite a resposta em streaming.

import asyncio
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)

asyncio.run(stream_run())

Saída esperada: O agente processa a mensagem e transmite as respostas em blocos. 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.

Bloqueia e desbloqueia o agente

Para agentes personalizados, o Foundry não tem acesso à infraestrutura subjacente onde o agente corre, 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. Esta funcionalidade permite aos administradores desativar um agente caso este se comporte mal.

Para bloquear solicitações recebidas para o 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.

   

5. Confirma a operação.

Depois de bloqueares o agente, o valor de Estado do agente na Foundry é Bloqueado. Os agentes no estado Bloqueado funcionam na infraestrutura associada mas não conseguem aceitar pedidos recebidos. O Foundry bloqueia qualquer tentativa de interface com o agente.

Para desbloquear o agente:

1. Seleciona Atualizar estado e depois seleciona Desbloquear.

2. Confirma 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:

• Corridas
• 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 traços e registos 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.

   

   Dica

   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 Agent Protocol 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).

Instrumentar 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 Conectar o Application Insights ao seu projeto Foundry.

Neste exemplo, configura-se um agente desenvolvido com LangGraph para emitir traços no padrão OpenTelemetry. O rastreador capta todas as operações do agente, incluindo chamadas 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, contacte 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 rastreios incluem nomes de operações, durações, chamadas de modelo, 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 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 do Azure Monitor para encaminhar dados ao Application Insights utilizando a sua cadeia de ligação. Para detalhes sobre como implementá-lo, veja Configure Azure Monitor OpenTelemetry.

Analisar traços de diagnóstico

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

Conteúdo relacionado

• O que é Microsoft Foundry Control Plane?
• Monitorize a saúde e o desempenho dos agentes em toda a sua frota
• Otimizar o custo e desempenho do modelo