Manage hosted agents

View, monitor, and manage hosted agents in Foundry Agent Service by using the REST API, Python SDK, or Azure Developer CLI.

This article shows you how to manage Hosted agents in Foundry Agent Service. After you deploy a Hosted agent, you can view its status, create new versions, select the version served by the agent endpoint, monitor logs, and delete agents when they’re no longer needed.

The platform manages the container lifecycle automatically. Compute is provisioned when a request arrives and deprovisioned after the idle timeout (15 minutes). This automatic compute scaling is separate from the agent’s endpoint state. You don’t start or stop the compute manually, but you can disable an agent’s endpoint to take it offline and enable it again later.

Prerequisites

• A deployed Hosted agent.

Set up variables

The REST API examples in this article use az rest to call the Foundry Agent Service endpoints directly. Set the following variables before running the commands:

ACCOUNT_NAME="<your-foundry-account-name>"
PROJECT_NAME="<your-project-name>"
AGENT_NAME="<your-agent-name>"
BASE_URL="https://${ACCOUNT_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}"
API_VERSION="v1"
RESOURCE="https://ai.azure.com"

The --resource parameter is required for all az rest calls to Foundry Agent Service data-plane endpoints. Without it, az rest can’t derive the correct Azure AD audience from the URL and authentication fails.

View agents and versions

Use the following commands to list agents and inspect version details.

List all agents in a project

Get agent details

Get a specific version

List all versions of an agent

Create a new version

Create a new agent version when you need to update the container image, change resource allocation, or modify environment variables.

Create a draft version (preview)

Draft versions are in preview. Preview features are provided without a service-level agreement and aren’t recommended for production workloads. Behavior can change. Draft creation must be enabled for your subscription; until it’s enabled, a request with draft set to true creates a normal release version instead.

A draft version is an experimental version that you can create and test without affecting how your agent serves production traffic. Drafts let you iterate on a new image, resource allocation, or configuration before you promote the change to a regular release version.

Draft versions differ from regular release versions in the following ways:

• Separate version identifier: A draft is assigned a draft-{timestamp} version string (for example, draft-1719600000000) instead of an auto-incremented integer, so it never advances your release version numbering.
• Excluded from default listings: Drafts don’t appear when you list versions unless you pass include_drafts=true.
• Excluded from implicit routing: A draft is never resolved as the agent’s latest version, so it doesn’t receive traffic automatically.
• Can’t be a traffic-routing target: You can’t pin a traffic-routing rule to a draft version. Requests to route traffic to a draft are rejected.

To create a draft version, set draft to true in the request body:

Version status values

After you create or update an agent version, poll the version endpoint until the status reaches active:

Status	Description
creating	Infrastructure is being provisioned (typically 2-5 minutes).
active	Agent is ready to serve requests.
failed	Provisioning failed. Check the error field in the response for details.
deleting	Version is being cleaned up.
deleted	Version has been fully removed.

Poll the version status after creation:

import time

def wait_for_version_active(project, agent_name, agent_version, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(10)
        version = project.agents.get_version(
            agent_name=agent_name, agent_version=agent_version
        )
        status = version["status"]
        print(f"Version status: {status} (attempt {attempt + 1})")
        if status == "active":
            return
        if status == "failed":
            raise RuntimeError(f"Version provisioning failed: {dict(version)}")
    raise RuntimeError("Timed out waiting for version to become active")

Disable or enable an agent

Disable an agent to take its endpoint offline without deleting the agent or any of its versions. While disabled, the agent rejects requests, but its configuration and versions remain intact. Enable the agent again whenever you’re ready to resume serving requests. Disabling is reversible, which makes it the preferred way to take an agent out of service temporarily.

Disable an agent

Enable an agent

Delete an agent

You can delete a specific version or an entire agent with all its versions.

Delete a specific version

Delete an agent and all versions

This action permanently deletes the agent and all its versions. Active sessions are terminated. This operation can’t be undone.

View logs and monitor

Access container logs for debugging provisioning and runtime issues.

Example log output

2026-04-09T08:43:48.72656  Connecting to the container 'agent-container'...
2026-04-09T08:43:48.75451  Successfully connected to container: 'agent-container'
2026-04-09T08:43:59.0671054Z stdout F INFO: 127.0.0.1:42588 - "GET /readiness HTTP/1.1" 200 OK

Configure agent endpoint routing

An agent endpoint routes 100% of its traffic to one agent version. Use the version selector to choose the version that the endpoint serves.

Traffic splitting between agent versions isn’t supported. Configure one FixedRatio rule with traffic_percentage set to 100, even though version_selection_rules is an array.

Retrieve the agent identity for role assignments

Each Hosted agent has an instance identity — a Microsoft Entra ID service principal that the agent uses at runtime to authenticate to downstream resources. To grant the agent access to services such as Azure Storage or Azure Cosmos DB, you need the identity’s principal ID so you can create RBAC role assignments.

For more information on how agent identities work, see Agent identity concepts.

Extract the agent identity principal ID

Assign roles to the agent identity

After you have the principal ID, assign RBAC roles to the agent identity at the appropriate resource scope. Use --assignee-object-id with --assignee-principal-type ServicePrincipal to avoid Microsoft Graph lookup issues with agent identity service principals.

The agent identity works with any Azure resource that supports RBAC. The following examples show two common scenarios: granting access to the Foundry project and granting access to a storage account.

Verify role assignments

Next steps

Agent applications

Related content

• What are Hosted agents?
• Deploy a Hosted agent
• Agent identity concepts
• Evaluate your AI agents