Migrate custom agents to external agents

Register your existing custom agent as an external agent in Microsoft Foundry by using the same OpenTelemetry agent ID. Keep its runtime, Azure API Management gateway, invocation URL, authentication, and policies unchanged.

Important

Custom agent registration in Microsoft Foundry Control Plane is scheduled for deprecation on April 30, 2027. You can no longer add new custom agents. Use external agents instead for evaluation, observability, and optimization use cases in Foundry.

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

External agent registration links your agent's telemetry to Foundry. It doesn't deploy a runtime, change API Management, or replace your existing gateway controls.

Warning

Don't unregister or delete the original custom agent or its API Management API as part of this migration. Deleting either can remove the existing invocation route.

Prerequisites

  • An existing custom agent registered in Foundry Control Plane.

  • The same Foundry project and connected Application Insights resource that you use for the custom agent's traces.

  • Agent instrumentation that emits the gen_ai.agent.id attribute.

  • Python 3.11 or later.

  • PowerShell and the Azure CLI. Run the commands in this article in the same PowerShell session.

  • The Foundry User role on the project to register the external agent.

  • The Reader or Monitoring Reader role on the connected Application Insights resource to view traces.

    Important

    The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

Sign in to the directory that contains your Foundry project:

az login

Get the existing OpenTelemetry agent ID

Preserve the exact existing gen_ai.agent.id. Don't generate a new ID or substitute the API Management API's name, display name, or resource ID.

  1. Open your existing custom agent's trace view in Foundry and select a recent trace.

  2. Select the agent span and copy its gen_ai.agent.id attribute.

  3. Set the copied value in your PowerShell session:

    $env:OTEL_AGENT_ID = "<gen_ai.agent.id-from-the-trace>"

If the attribute is missing, check the running agent's instrumentation before continuing. For tracing setup, see Set up tracing in Foundry.

Register the external agent

Install the SDK and set the Foundry project endpoint, not the gateway or backend URL. Keep OTEL_AGENT_ID unchanged.

python -m pip install "azure-ai-projects>=2.3.0" azure-identity

$env:FOUNDRY_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"

Save the following code as register_external_agent.py. Replace travel-planner with an unused Foundry agent name. The SDK uses your Azure CLI sign-in, and allow_preview=True enables the external agent preview.

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ExternalAgentDefinition
from azure.identity import AzureCliCredential

with AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=AzureCliCredential(),
    allow_preview=True,
) as project_client:
    registered = project_client.agents.create_version(
        agent_name="travel-planner",
        description="Travel planner hosted outside Foundry.",
        definition=ExternalAgentDefinition(
            otel_agent_id=os.environ["OTEL_AGENT_ID"],
        ),
    )
    saved = project_client.agents.get_version(
        agent_name=registered.name,
        agent_version=registered.version,
    )
    print(f"Registered agent: {saved.name}")
    print(f"OpenTelemetry agent ID: {saved.definition.otel_agent_id}")

Reference: AIProjectClient, ExternalAgentDefinition, AgentsOperations, and AzureCliCredential.

Run the script:

python register_external_agent.py

The output echoes the preserved telemetry ID, for example:

Registered agent: travel-planner
OpenTelemetry agent ID: com.contoso.travel-planner

If the name already exists, create_version creates another registration version rather than a separate agent.

These examples target Azure public cloud. For another cloud, use the Foundry endpoint and SDK authentication settings supported by that cloud.

Check invocation and traces

Send a normal request through the same gateway URL and authentication as before. Confirm that:

  • The agent still responds as before.
  • The SDK readback shows the existing telemetry ID.
  • New traces appear under the external agent in Foundry.

Keep the original custom agent registration and API Management API in place. External agent registration doesn't proxy traffic or provide gateway-based blocking; your existing gateway continues to handle invocation.

Troubleshoot missing traces

Check the project, connected Application Insights resource, exact telemetry ID, time range, sampling, and ingestion delay. Registration doesn't create traces or copy historical telemetry.

In Application Insights Logs, replace the example ID with the value you copied from the trace:

union requests, dependencies
| where ['timestamp'] > ago(30m)
| where tostring(['customDimensions']['gen_ai.agent.id'])
    == "com.contoso.travel-planner"
| project ['timestamp'], ['name'], ['operation_Id'],
    ['otelAgentId'] = tostring(['customDimensions']['gen_ai.agent.id'])
| order by ['timestamp'] desc
| take 20

Agent spans can be in requests or dependencies. A matching row confirms ingestion and identity. Also confirm that the trace is visible under the external agent in Foundry.

Related content

  • Last updated on