Skip to main content
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, configure traffic routing, 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). There are no manual start or stop operations.

​
Prerequisites

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

​
Version status values

After you create or update an agent version, poll the version endpoint until the status reaches active:
StatusDescription
creatingInfrastructure is being provisioned (typically 2-5 minutes).
activeAgent is ready to serve requests.
failedProvisioning failed. Check the error field in the response for details.
deletingVersion is being cleaned up.
deletedVersion 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")

​
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

Agent endpoints control how traffic is distributed across agent versions. Use version selectors to route a percentage of traffic to specific versions, enabling canary deployments or gradual rollouts.

​
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