Guide · Agent skill

How to use the Azure Hosted Agents (Python) agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

This skill is a set of written instructions and code sketches that teaches an AI agent how to create hosted agents in Microsoft Azure AI Foundry. A hosted agent is an agent packaged as your own container image and deployed to Azure using the Python Azure AI Projects SDK. After reading this guide you will know how to install the skill, what it needs, how to ask for it in plain language, and which safety checks to run before provisioning anything.

Azure Hosted Agents (Python)sickn33/agentic-awesome-skills · MIT Download the skill

Quick start

1Download and install the skill. Download the ZIP from the skill page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Or upload it in the Claude apps under Settings, Capabilities, Skills.
2Install the Python packages. Run pip install with the pinned azure-ai-projects version and azure-identity. Confirm the installed SDK supports HostedAgentDefinition.
3Set the project endpoint. Export AZURE_AI_PROJECT_ENDPOINT with your Azure AI Foundry project endpoint so the client can connect.
4Confirm prerequisites. Push your container image to Azure Container Registry and grant the project identity the required pull role. Check hosted-agent availability for your region and project.
5Create, check and clean up. Call create_version with your HostedAgentDefinition, inspect the returned version and its status, and delete versions you no longer need.

What the agents-v2-py skill makes the agent do

Once installed, the skill gives the agent step-by-step guidance for the hosted-agent workflow. It covers the prerequisites (container registry access, permissions and SDK version), authentication with DefaultAzureCredential, creating agent versions with HostedAgentDefinition, listing versions, deleting versions, and setting CPU, memory and environment variables.

Explains the prerequisites: a container image pushed to Azure Container Registry, pull permissions for the project identity, hosted-agent availability, and the pinned SDK version
Shows how to create, list and delete agent versions with the Python SDK
Documents the HostedAgentDefinition parameters: protocol_versions, container_configuration, cpu, memory and environment_variables

Install the agents-v2-py skill

Download the ZIP from the skill page on this directory and unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only inside one project. Alternatively, in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

The package contains a single file, SKILL.md. It has no bundled scripts, so there is nothing to run during installation.

Set up the Python packages and environment

The skill expects Python with pip and two packages: the Azure AI Projects SDK at the pinned version and azure-identity. Install them with the command below, then set your project endpoint as an environment variable. The endpoint has the form shown in the code.

Use the approved Azure credential flow for the tenant and subscription you intend to use
Keep non-secret values such as deployment names and a reviewed image reference in configuration

pip install 'azure-ai-projects==2.3.0' azure-identity
export AZURE_AI_PROJECT_ENDPOINT='https://<resource>.services.ai.azure.com/api/projects/<project>'

Create a hosted agent with a container image

The skill's core example authenticates with DefaultAzureCredential, then calls create_version with a HostedAgentDefinition. The definition names the protocol, the CPU and memory, a reviewed container image, and any environment variables the container needs. The image is read from an environment variable named REVIEWED_CONTAINER_IMAGE in the example.

A created version does not prove that the container is running healthily. The skill tells you to inspect the returned model and check status fields with get_version.

protocol_versions: required; the protocol versions the agent supports (the example uses the RESPONSES protocol)
container_configuration: required for an image deployment; points to the reviewed registry image
cpu and memory: optional, for example 1 core and 2Gi
environment_variables: optional dictionary passed into the container

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (HostedAgentDefinition, ContainerConfiguration, ProtocolVersionRecord, AgentEndpointProtocol)
import os

client = AIProjectClient(endpoint=os.environ['AZURE_AI_PROJECT_ENDPOINT'], credential=DefaultAzureCredential())
agent = client.agents.create_version(
    agent_name='my-hosted-agent',
    definition=HostedAgentDefinition(
        protocol_versions=[ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version='2.0.0')],
        cpu='1',
        memory='2Gi',
        container_configuration=ContainerConfiguration(image=os.environ['REVIEWED_CONTAINER_IMAGE']),
        environment_variables={'AZURE_AI_PROJECT_ENDPOINT': os.environ['AZURE_AI_PROJECT_ENDPOINT'], 'MODEL_NAME': os.environ['MODEL_DEPLOYMENT_NAME']}
    )
)
print(f'Created agent: {agent.name} (version: {agent.version})')

List and delete agent versions

To review what exists, list the versions of an agent by name. To remove a version you no longer need, delete it by agent name and version. Deleting a version is the cleanup step to run after a test, since hosted resources can carry cloud costs.

Close synchronous clients and credentials with their context managers or close() methods

versions = client.agents.list_versions(agent_name='my-hosted-agent')
for version in versions:
    print(f'Version: {version.version}')

client.agents.delete_version(agent_name='my-hosted-agent', agent_version=agent.version)

Trigger the skill with natural requests

You do not need to name the skill. The skill's description says it applies when you are creating hosted agents with custom container images in Azure AI Foundry, so a request that matches that topic should bring it into play. Being specific about the platform and the container helps the agent pick the right guidance.

Help me create a hosted agent in Azure AI Foundry from my custom container image using the Python SDK
Show me how to set cpu, memory and environment variables for a HostedAgentDefinition
What prerequisites do I need before I create a hosted agent from an Azure Container Registry image?
Write a script that lists and deletes old versions of my hosted agent

Safety notes before you provision

The source marks this skill as critical risk. It runs no scripts and bundles no executable files, but it does use the network, and the code it guides you through talks to Azure. The skill itself warns that reading its documentation is not a cloud integration test, so you must validate the installed SDK and the service support before provisioning.

Creating agents can incur cloud costs and can expose network endpoints; review the network policy first and do not enable public hosting by assumption
Review the container image before deploying it, and reference it by a reviewed image identifier
Grant the project identity only the registry role that the skill names for its permission mode (Container Registry Repository Reader in the current guidance)
Do not place secrets in environment dictionaries on the assumption that they are protected; use the platform's actual protected injection mechanism

What people use it for

Deploying a custom Python agent container, such as a data processing agent, as a hosted agent in Azure AI Foundry
Keeping a reference of HostedAgentDefinition parameters for a team that provisions agents by hand
Listing and removing old agent versions after testing so unused resources do not linger

Frequently asked questions

How do I install the agents-v2-py skill?

Download the ZIP from the skill page and unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder for one project. In the Claude apps you can instead upload it under Settings, Capabilities, Skills. The package contains only SKILL.md.

What do I need to use this skill?

You need Python with pip, the azure-ai-projects package at the pinned version, azure-identity, an Azure subscription with an AI Foundry project and endpoint, and a container image in Azure Container Registry. The project identity must have pull permission on that registry.

Is the agents-v2-py skill free?

The skill is listed under the MIT licence. Azure itself is not free: the source warns that creating agents can incur cloud costs, so check Azure pricing for your resources before provisioning.

Does the skill deploy the agent for me?

No. The skill is instructions and code sketches. It does not deploy anything unless you run the code yourself against your own Azure project.

Can I use this skill with AWS or Google Cloud?

No. It only covers Microsoft Azure AI Foundry and the Azure AI Projects SDK. For other clouds you would need a different skill or platform documentation.

Why does my hosted agent version show as created but not work?

The source notes that a created version is not proof that the container is healthy. Inspect the returned model and its status fields with get_version, confirm the image pull permission, and check the container's logs and environment variables.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill is useful for Python developers already working in Azure AI Foundry who need a reference for deploying a custom container as a hosted agent and for the HostedAgentDefinition parameters. Anyone not using Azure AI Foundry should choose a different skill, and teams should review the network exposure and cloud costs before provisioning anything.

Download the skill