Register and manage custom agents

Microsoft Foundry Control Plane provides centralized management and observability for agents running across different platforms and infrastructures. This article covers management and diagnostic data for existing custom agents.

For the transition steps, see Migrate custom agents to external agents.

Prerequisites

• An Azure account with an active subscription. If you don't have one, create a free Azure account, which includes a free trial subscription.

• A Foundry project. If you don't have one, create a project.

• An existing custom agent registered in Foundry Control Plane.

• The existing AI gateway configured in your Foundry resource and the agent's reachable backend endpoint.

Add a custom agent

You can no longer add a new custom agent in Foundry Control Plane. For a new integration, register an external agent. For an existing custom agent, follow the migration guide.

Existing custom agent architecture

Existing custom agents use API Management as a proxy for communications to the agent, so it can control access and monitor activity.

Connect clients to the agent

An existing custom agent registration has a gateway URL for clients to use. Because the gateway acts as a proxy for communications to your agent, it can control access and monitor activity. Keep using this URL during migration to external agent registration.

To find the existing gateway URL:

1. In the agents list, select the radio button next to the custom agent's name to open the information pane. Don't select the agent name itself, because that link navigates away from the Assets pane.

2. On the information pane, under Agent URL, select the Copy option.

   

3. Keep using this gateway URL to call the agent.

In this example, clients use the LangGraph SDK and the existing gateway URL to call a LangGraph agent. This code creates a thread, sends a message asking about the weather, and streams the response back.

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

Expected output: The agent processes the message and streams back responses as chunks. Each chunk contains partial results from the agent's execution. These results might include tool calls to the weather function and the final response about Los Angeles weather.

Block and unblock the agent

For custom agents, Foundry doesn't have access to the underlying infrastructure where the agent runs, so start and stop operations aren't available. However, Foundry can block incoming requests to the agent so that clients can't consume it. This capability allows administrators to disable an agent if it misbehaves.

To block incoming requests to your agent:

1. On the toolbar, select Operate.

2. On the left pane, select Assets.

3. Select the radio button next to the agent that you want to block. The information pane appears. Don't select the agent name, because that link navigates away from the Assets pane.

4. Select Update status, and then select Block.

   

5. Confirm the operation.

After you block the agent, the Status value of the agent in Foundry is Blocked. Agents in the Blocked state run in their associated infrastructure but can't take incoming requests. Foundry blocks any attempt to interface with the agent.

To unblock the agent:

1. Select Update status, and then select Unblock.

2. Confirm the operation.

Enable diagnostic data for the agent

Foundry uses the OpenTelemetry open standard to understand what agents are doing. If your project has Application Insights configured, Foundry logs requests into Application Insights by default. Foundry also uses this data to compute:

• Runs
• Error rate
• Usage (if available)

To get the best level of fidelity, Foundry expects custom agents to comply with the semantic conventions for generative AI solutions in the OpenTelemetry standard.

View traces and logs sent to Foundry

1. On the toolbar, select Operate.

2. On the left pane, select Assets.

3. Select the radio button next to the agent to open the information pane. Don't select the agent name, because that link navigates away from the Assets pane.

4. The Traces section shows one entry for each HTTP call made to the agent's endpoint.

   To see the details, select an entry.

   

   Tip

   In this example, you can see how clients use the new agent's endpoint to communicate with the agent. The example shows an agent served with the Agent Protocol from LangChain. Clients use the route /runs/stream.

In this example, the trace doesn't include any details beyond the HTTP post. The agent's code doesn't include any further instrumentation. In the next section, you learn how to instrument your code and get details like tool calls and large language model (LLM) calls.

Instrument custom code agents

If you build your agent by using custom code, instrument your solution to emit traces according to the OpenTelemetry standard and send them to Application Insights. Instrumentation gives Foundry access to detailed information about what your agent is doing.

Send traces to the Application Insights resource of your project by using its instrumentation key. To get the instrumentation key associated with your project, follow the instructions at Connect Application Insights to your Foundry project.

In this example, you configure an agent developed with LangGraph to emit traces in the OpenTelemetry standard. The tracer captures all agent operations, including tool calls and model interactions. The tracer then sends the operations to Application Insights for monitoring.

This code uses the langchain-azure-ai package. For guidance on instrumenting specific solutions with OpenTelemetry, depending on the programming language and framework that your solution uses, see Language APIs & SDKs.

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

Then, instrument your agent:

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] })

Expected output: The agent runs normally while automatically emitting OpenTelemetry traces to Application Insights. Traces include operation names, durations, model calls, tool invocations, and token usage. You can view these traces in the Foundry portal, in the Traces section.

Instrument platform solutions

If your agent runs on a platform solution that supports OpenTelemetry but doesn't support Application Insights, deploy an OpenTelemetry collector and configure your software to send OTLP data to the collector (standard OpenTelemetry configuration).

Configure the collector with the Azure Monitor exporter to forward data to Application Insights by using your connection string. For details about how to implement it, see Configure Azure Monitor OpenTelemetry.

Troubleshoot traces

If you don't see traces, check the following items:

Related content

• Migrate custom agents to external agents
• What is Microsoft Foundry Control Plane?
• Monitor agent health and performance across your fleet