Manage hosted agent lifecycle

This article shows you how to manage hosted agent deployments in Foundry Agent Service. After you deploy a hosted agent, you can start, stop, update, and delete it as your needs change.

Prerequisites

• A deployed hosted agent

• Azure CLI version 2.80 or later

• Azure Cognitive Services CLI extension:

  az extension add --name cognitiveservices --upgrade
  

Start an agent deployment

Start a hosted agent to make it available for requests. Use this command to start a new deployment or restart a stopped agent.

az cognitiveservices agent start \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent \
    --agent-version 1 \
    --min-replicas 1 \
    --max-replicas 2

State transitions when starting:

• Stopped → Starting → Started (success) or Failed (error)

Stop an agent deployment

Stop a running agent to pause processing and reduce costs. The agent version remains available for restarting later.

az cognitiveservices agent stop \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent \
    --agent-version 1

State transitions when stopping:

• Running → Stopping → Stopped (success) or Running (error)

Update an agent

You can update agents with versioned or non-versioned changes.

Versioned updates

Versioned updates create a new agent version. Use them for:

• Container image changes
• CPU or memory allocation changes
• Environment variable modifications
• Protocol version updates

You can create a new version using the Azure CLI.

Create version using Azure CLI

For CLI-based version creation, see az cognitiveservices agent create.

Non-versioned updates

Non-versioned updates modify scaling or metadata without creating a new version:

az cognitiveservices agent update \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent \
    --agent-version 1 \
    --min-replicas 2 \
    --max-replicas 5 \
    --description "Updated production agent"

Delete an agent

Delete a deployment only

Stop the agent deployment but keep the version definition for later use:

az cognitiveservices agent delete-deployment \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent \
    --agent-version 1

Delete a specific version

Delete an agent version and its deployment:

az cognitiveservices agent delete \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent \
    --agent-version 1

Delete all versions

Remove all versions of an agent:

az cognitiveservices agent delete \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent

Delete using the SDK

project.agents.delete_version(agent_name="my-agent", agent_version="1")

List and view agents

List all versions of an agent

az cognitiveservices agent list-versions \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent

Show agent details

az cognitiveservices agent show \
    --account-name myAccount \
    --project-name myProject \
    --name myAgent

View container logs

Access container logs for debugging startup and runtime issues.

REST API

GET https://{endpoint}/api/projects/{projectName}/agents/{agentName}/versions/{agentVersion}/containers/default:logstream

Timeouts:

• Maximum connection duration: 10 minutes
• Idle timeout: 1 minute

Example console log response

2025-12-15T08:43:48.72656  Connecting to the container 'agent-container'...
2025-12-15T08:43:48.75451  Successfully Connected to container: 'agent-container'
2025-12-15T08:33:59.0671054Z stdout F INFO: 127.0.0.1:42588 - "GET /readiness HTTP/1.1" 200 OK

Invoke a hosted agent

Test your running agent using the SDK:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create project and OpenAI clients
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)
openai = project.get_openai_client()

# Get agent details
agent = project.agents.get(agent_name=AGENT_NAME)

# Chat with the hosted agent
response = openai.responses.create(
    input=[{"role": "user", "content": "Hello! What can you help me with?"}],
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}}
)

print(f"Response: {response.output_text}")

You can also test agents in the agent playground UI in the Foundry portal.

Troubleshooting

Agent fails to start

Agent starts but doesn't respond

1. Check container logs for runtime errors
2. Verify the hosting adapter is correctly configured
3. Confirm environment variables are set correctly
4. Test the agent locally before deploying

Common pitfalls

• Forgetting ACR permissions: The project's managed identity needs explicit pull access to the container registry
• Incorrect platform version for docker images: Always specify --platform linux/amd64 when doing docker build yourself
• Wrong SDK version: Hosted agents require azure-ai-projects>=2.0.0
• Missing capability host: Create an account-level capability host before deploying. See Deploy a hosted agent
• Publishing identity mismatch: After publishing, the agent uses a different identity. Reassign RBAC permissions

Next steps

Related content

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