Register and manage custom agents

The Microsoft Foundry Control Plane provides centralized management and observability for agents running across different platforms and infrastructures. You can register custom agents—running in Azure compute services or other cloud environments—to gain visibility into their operations and control their behavior.

This article shows you how to register a custom agent in the Foundry Control Plane. You learn how to configure your agent for registration, set up telemetry collection, and use the Control Plane's management capabilities.

Prerequisites

Before getting started, make sure you have:

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

• Foundry uses Azure API Management to register agents as APIs. Configure AI Gateway in your Foundry resource.

• An agent that you deploy and expose through a reachable endpoint (either a public endpoint or an endpoint reachable from the network where you deploy the Foundry resource).

Add a custom agent

You can register a custom agent in the Control Plane. Develop the agent in the technology of your choice, both platform and infrastructure solutions.

When you register a custom agent, Foundry uses Azure API Management to act as a proxy for communications to your agent, so it can control access and monitor activity.

When you register a custom agent the resulting architecture is as follows:

Verify your agent

Verify that your agent meets the requirements for registration:

Prepare your Foundry project

Custom agents are added to Foundry projects. Before registering the agent, let's make sure you configured the project correctly.

1. Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).

   

2. Ensure AI Gateway is configured in your project:

   1. Select Operate > Admin console.

   2. Open the AI Gateway tab.

   3. The page lists all the AI Gateways configured and mapped to a Foundry resource. Check if the Foundry resource you want to use has an AI Gateway associated.

      

   4. If the Foundry resource you want to use doesn't have an AI Gateway configured (it isn't listed), add one using the option Add AI Gateway. AI Gateway is free to set up and unlocks powerful governance features like security, telemetry, and rate limits for your agents, tools, and models.

   5. For more details about how to configure AI Gateway, see Create an AI Gateway.

3. Ensure you have observability configured in the project. Control Plane uses the Azure Application Insights resource associated with your selected project for emitting telemetry to help you diagnose your agent:

   1. Select Operate > Admin console.

   2. Under All projects, use the search box to look for your project.

   3. Select the project.

   4. Select the tab Connected resources.

   5. Ensure there is a resource associated under the category Application Insights.

      

   6. If there is no resource associated, add one by selecting Add connection and select Application Insights.

   7. Your project is configured for observability and tracing.

Register the agent

To register the agent, follow these steps:

1. Select Operate from the upper-right navigation.

2. Select the Overview pane.

3. Select Register agent.

   

4. The registration wizard appears. First, complete the details about the agent you want to register. The following properties describe the agent as it runs on its platform

   Property	Description	Required
   Agent URL	It represents the endpoint (URL) where your agent runs and receives requests. In general, but depending on your protocol, you indicate the base URL that your clients use. For example, if your agent talks OpenAI Chat Completions API, you indicate https://<host>/v1/ - without /chat/completions as clients generally add it.	Yes
   Protocol	The communication protocol supported by your agent. Use HTTP in general, or if your agent supports more specifically A2A, indicate that one	Yes
   A2A agent card URL	Path to the agent card JSON specification. If you don't specify it, the system uses the default /.well-known/agent-card.json.	No
   OpenTelemetry Agent ID	The Agent ID your agent uses to emit traces according to OpenTelemetry Generative AI semantic conventions. Traces indicate it in attribute gen_ai.agents.id for spans with operation name create_agent. If you don't specify this, the system uses the Agent name value to find traces and logs that this new agent reports.	No
   Admin portal URL	The administration portal URL where you can perform further administration operations for this agent. Foundry can store this value for easy access convenience. Foundry doesn't have any access to perform operations directly to such management portal.	No

5. Then, configure how you want the agent to show up in the Control Plane:

   Property	Description	Required
   Project	The project where you register the agent. Foundry uses the AI Gateway configured in the resource where the project lives to configure the inbound endpoint to the agent. You can only select projects with AI Gateway enabled in their resources. If you don't see any, configure AI Gateway in your Foundry resource. It's also advisable to configure Azure Application Insights in the selected project. Foundry uses the project's Azure Application Insights resource to sink traces and logs.	Yes
   Agent name	The name of the agent as you want it to appear in Foundry. The system might also use this name to find relevant traces and logs in Azure Application Insights if you don't specify a different value in the field OpenTelemetry Agent ID.	Yes
   Description	A clear description about this agent.	No

6. Save the changes.

7. Foundry adds the new agent. Select the Assets tab in the left pane to check the list of agents.

8. To show only custom agents, use the Source filter and select Custom.

   

Connect clients to the agent

When you register your agent in Foundry, you get a new URL for your clients to use. Foundry acts as a proxy for communications to your agent, so it can control access and monitor activity.

To distribute the new URL for your clients to call the agent:

1. Select the custom agent using the radio selector.

2. On the details panel on the right, under Agent URL, select the copy option.

   

3. Use the new URL to call the agent instead of the original endpoint.

In this example, you deploy a LangGraph agent and clients use the LangGraph SDK to consume it. The client uses the new agent URL value. This code creates a thread, sends a message asking about the weather, and streams the response back.

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)

Expected output: The agent processes the message and streams back responses as chunks. Each chunk contains partial results from the agent's execution, which 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, preventing clients from consuming it. This capability allows administrators to disable an agent if it misbehaves.

To block incoming requests to your agent:

1. Select Operate from the upper-right navigation.

2. Select Assets in the left pane.

3. Select the agent you want to block. The information panel appears.

4. Select Update status and then select Block.

   

5. Confirm the operation.

After you block the agent, the Status of the agent in Foundry shows as 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 telemetry for your agent

Foundry uses the OpenTelemetry open standard to understand what agents are doing. If your project has Azure Application Insights configured, Foundry logs requests into Azure Application Insights by default. This telemetry is also used 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 solution in the OpenTelemetry standard.

View runs and traces

You can view traces and logs sent to Foundry. To view them:

1. Select Operate from the upper-right navigation.

2. Select Assets in the left pane.

3. Select the agent.

4. Traces sections show up.

5. You see one entry for each HTTP call made to the agent's endpoint.

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

7. Notice in this example that no further details besides the HTTP post are present in the trace. This is because no further instrumentation was added to the agent's code. See the next section to learn how to instrument your code and gain further details like tool calls, LLM calls, etc.

Instrument custom code agents

If you build your agent with custom code, you need to instrument your solution to emit traces according to the OpenTelemetry standard and sink them to Azure Application Insights. Instrumentation allows Foundry to have access to higher level of detail about what your agent is doing.

Send traces to the Azure Application Insights resource of your project by using its instrumentation key. To get the instrumentation key associated with your project, follow the instructions at Enable tracing in your 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, and sends them to Azure Application Insights for monitoring.

This code uses langchain-azure-ai package. Learn how to instrument specific solutions with OpenTelemetry depending on the programming language and the framework used in your solution at 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 Azure Application Insights. Traces include operation names, durations, model calls, tool invocations, and token usage. You can view these traces in the Foundry portal under the Traces section.

Instrumenting platform solutions

If your agent runs on a platform solution that supports OpenTelemetry but doesn't support Azure Application Insights, you need to 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, see Configure Azure Monitor OpenTelemetry.

Troubleshooting traces

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

Related content

• What is the Microsoft Foundry Control Plane?
• Monitor agents across your fleet
• Optimize cost and performance across your agent fleet