{"id":"50e02436-030a-4f52-a143-3df584521790","shortId":"rgnbsE","kind":"skill","title":"hosted-agents-v2-py","tagline":"Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry.","description":"# Azure AI Hosted Agents (Python)\n\nBuild container-based hosted agents using `ImageBasedHostedAgentDefinition` from the Azure AI Projects SDK.\n\n## Installation\n\n```bash\npip install azure-ai-projects>=2.0.0b3 azure-identity\n```\n\n**Minimum SDK Version:** `2.0.0b3` or later required for hosted agent support.\n\n## Environment Variables\n\n```bash\nAZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>\n```\n\n## Prerequisites\n\nBefore creating hosted agents:\n\n1. **Container Image** - Build and push to Azure Container Registry (ACR)\n2. **ACR Pull Permissions** - Grant your project's managed identity `AcrPull` role on the ACR\n3. **Capability Host** - Account-level capability host with `enablePublicHostingEnvironment=true`\n4. **SDK Version** - Ensure `azure-ai-projects>=2.0.0b3`\n\n## Authentication\n\nAlways use `DefaultAzureCredential`:\n\n```python\nfrom azure.identity import DefaultAzureCredential\nfrom azure.ai.projects import AIProjectClient\n\ncredential = DefaultAzureCredential()\nclient = AIProjectClient(\n    endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n    credential=credential\n)\n```\n\n## Core Workflow\n\n### 1. Imports\n\n```python\nimport os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.ai.projects import AIProjectClient\nfrom azure.ai.projects.models import (\n    ImageBasedHostedAgentDefinition,\n    ProtocolVersionRecord,\n    AgentProtocol,\n)\n```\n\n### 2. Create Hosted Agent\n\n```python\nclient = AIProjectClient(\n    endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n    credential=DefaultAzureCredential()\n)\n\nagent = client.agents.create_version(\n    agent_name=\"my-hosted-agent\",\n    definition=ImageBasedHostedAgentDefinition(\n        container_protocol_versions=[\n            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version=\"v1\")\n        ],\n        cpu=\"1\",\n        memory=\"2Gi\",\n        image=\"myregistry.azurecr.io/my-agent:latest\",\n        tools=[{\"type\": \"code_interpreter\"}],\n        environment_variables={\n            \"AZURE_AI_PROJECT_ENDPOINT\": os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n            \"MODEL_NAME\": \"gpt-4o-mini\"\n        }\n    )\n)\n\nprint(f\"Created agent: {agent.name} (version: {agent.version})\")\n```\n\n### 3. List Agent Versions\n\n```python\nversions = client.agents.list_versions(agent_name=\"my-hosted-agent\")\nfor version in versions:\n    print(f\"Version: {version.version}, State: {version.state}\")\n```\n\n### 4. Delete Agent Version\n\n```python\nclient.agents.delete_version(\n    agent_name=\"my-hosted-agent\",\n    version=agent.version\n)\n```\n\n## ImageBasedHostedAgentDefinition Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `container_protocol_versions` | `list[ProtocolVersionRecord]` | Yes | Protocol versions the agent supports |\n| `image` | `str` | Yes | Full container image path (registry/image:tag) |\n| `cpu` | `str` | No | CPU allocation (e.g., \"1\", \"2\") |\n| `memory` | `str` | No | Memory allocation (e.g., \"2Gi\", \"4Gi\") |\n| `tools` | `list[dict]` | No | Tools available to the agent |\n| `environment_variables` | `dict[str, str]` | No | Environment variables for the container |\n\n## Protocol Versions\n\nThe `container_protocol_versions` parameter specifies which protocols your agent supports:\n\n```python\nfrom azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol\n\n# RESPONSES protocol - standard agent responses\ncontainer_protocol_versions=[\n    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version=\"v1\")\n]\n```\n\n**Available Protocols:**\n| Protocol | Description |\n|----------|-------------|\n| `AgentProtocol.RESPONSES` | Standard response protocol for agent interactions |\n\n## Resource Allocation\n\nSpecify CPU and memory for your container:\n\n```python\ndefinition=ImageBasedHostedAgentDefinition(\n    container_protocol_versions=[...],\n    image=\"myregistry.azurecr.io/my-agent:latest\",\n    cpu=\"2\",      # 2 CPU cores\n    memory=\"4Gi\"  # 4 GiB memory\n)\n```\n\n**Resource Limits:**\n| Resource | Min | Max | Default |\n|----------|-----|-----|---------|\n| CPU | 0.5 | 4 | 1 |\n| Memory | 1Gi | 8Gi | 2Gi |\n\n## Tools Configuration\n\nAdd tools to your hosted agent:\n\n### Code Interpreter\n\n```python\ntools=[{\"type\": \"code_interpreter\"}]\n```\n\n### MCP Tools\n\n```python\ntools=[\n    {\"type\": \"code_interpreter\"},\n    {\n        \"type\": \"mcp\",\n        \"server_label\": \"my-mcp-server\",\n        \"server_url\": \"https://my-mcp-server.example.com\"\n    }\n]\n```\n\n### Multiple Tools\n\n```python\ntools=[\n    {\"type\": \"code_interpreter\"},\n    {\"type\": \"file_search\"},\n    {\n        \"type\": \"mcp\",\n        \"server_label\": \"custom-tool\",\n        \"server_url\": \"https://custom-tool.example.com\"\n    }\n]\n```\n\n## Environment Variables\n\nPass configuration to your container:\n\n```python\nenvironment_variables={\n    \"AZURE_AI_PROJECT_ENDPOINT\": os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n    \"MODEL_NAME\": \"gpt-4o-mini\",\n    \"LOG_LEVEL\": \"INFO\",\n    \"CUSTOM_CONFIG\": \"value\"\n}\n```\n\n**Best Practice:** Never hardcode secrets. Use environment variables or Azure Key Vault.\n\n## Complete Example\n\n```python\nimport os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.ai.projects import AIProjectClient\nfrom azure.ai.projects.models import (\n    ImageBasedHostedAgentDefinition,\n    ProtocolVersionRecord,\n    AgentProtocol,\n)\n\ndef create_hosted_agent():\n    \"\"\"Create a hosted agent with custom container image.\"\"\"\n    \n    client = AIProjectClient(\n        endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n        credential=DefaultAzureCredential()\n    )\n    \n    agent = client.agents.create_version(\n        agent_name=\"data-processor-agent\",\n        definition=ImageBasedHostedAgentDefinition(\n            container_protocol_versions=[\n                ProtocolVersionRecord(\n                    protocol=AgentProtocol.RESPONSES,\n                    version=\"v1\"\n                )\n            ],\n            image=\"myregistry.azurecr.io/data-processor:v1.0\",\n            cpu=\"2\",\n            memory=\"4Gi\",\n            tools=[\n                {\"type\": \"code_interpreter\"},\n                {\"type\": \"file_search\"}\n            ],\n            environment_variables={\n                \"AZURE_AI_PROJECT_ENDPOINT\": os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n                \"MODEL_NAME\": \"gpt-4o-mini\",\n                \"MAX_RETRIES\": \"3\"\n            }\n        )\n    )\n    \n    print(f\"Created hosted agent: {agent.name}\")\n    print(f\"Version: {agent.version}\")\n    print(f\"State: {agent.state}\")\n    \n    return agent\n\nif __name__ == \"__main__\":\n    create_hosted_agent()\n```\n\n## Async Pattern\n\n```python\nimport os\nfrom azure.identity.aio import DefaultAzureCredential\nfrom azure.ai.projects.aio import AIProjectClient\nfrom azure.ai.projects.models import (\n    ImageBasedHostedAgentDefinition,\n    ProtocolVersionRecord,\n    AgentProtocol,\n)\n\nasync def create_hosted_agent_async():\n    \"\"\"Create a hosted agent asynchronously.\"\"\"\n    \n    async with DefaultAzureCredential() as credential:\n        async with AIProjectClient(\n            endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n            credential=credential\n        ) as client:\n            agent = await client.agents.create_version(\n                agent_name=\"async-agent\",\n                definition=ImageBasedHostedAgentDefinition(\n                    container_protocol_versions=[\n                        ProtocolVersionRecord(\n                            protocol=AgentProtocol.RESPONSES,\n                            version=\"v1\"\n                        )\n                    ],\n                    image=\"myregistry.azurecr.io/async-agent:latest\",\n                    cpu=\"1\",\n                    memory=\"2Gi\"\n                )\n            )\n            return agent\n```\n\n## Common Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `ImagePullBackOff` | ACR pull permission denied | Grant `AcrPull` role to project's managed identity |\n| `InvalidContainerImage` | Image not found | Verify image path and tag exist in ACR |\n| `CapabilityHostNotFound` | No capability host configured | Create account-level capability host |\n| `ProtocolVersionNotSupported` | Invalid protocol version | Use `AgentProtocol.RESPONSES` with version `\"v1\"` |\n\n## Best Practices\n\n1. **Version Your Images** - Use specific tags, not `latest` in production\n2. **Minimal Resources** - Start with minimum CPU/memory, scale up as needed\n3. **Environment Variables** - Use for all configuration, never hardcode\n4. **Error Handling** - Wrap agent creation in try/except blocks\n5. **Cleanup** - Delete unused agent versions to free resources\n\n## Reference Links\n\n- [Azure AI Projects SDK](https://pypi.org/project/azure-ai-projects/)\n- [Hosted Agents Documentation](https://learn.microsoft.com/azure/ai-services/agents/how-to/hosted-agents)\n- [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/)\n\n## When to Use\nThis skill is applicable to execute the workflow or actions described in the overview.\n\n## Limitations\n- Use this skill only when the task clearly matches the scope described above.\n- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.\n- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.","tags":["hosted","agents","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows"],"capabilities":["skill","source-sickn33","skill-hosted-agents-v2-py","topic-agent-skills","topic-agentic-skills","topic-ai-agent-skills","topic-ai-agents","topic-ai-coding","topic-ai-workflows","topic-antigravity","topic-antigravity-skills","topic-claude-code","topic-claude-code-skills","topic-codex-cli","topic-codex-skills"],"categories":["antigravity-awesome-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/sickn33/antigravity-awesome-skills/hosted-agents-v2-py","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add sickn33/antigravity-awesome-skills","source_repo":"https://github.com/sickn33/antigravity-awesome-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 34768 github stars · SKILL.md body (9,261 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T18:51:28.344Z","embedding":null,"createdAt":"2026-04-18T21:38:37.646Z","updatedAt":"2026-04-23T18:51:28.344Z","lastSeenAt":"2026-04-23T18:51:28.344Z","tsv":"'/api/projects/':80 '/async-agent:latest':719 '/azure/ai-services/agents/how-to/hosted-agents)':841 '/azure/container-registry/)':847 '/data-processor:v1.0':595 '/my-agent:latest':220,411 '/project/azure-ai-projects/)':835 '0.5':429 '1':86,160,214,320,431,721,778 '1gi':433 '2':97,179,321,413,414,597,789 '2.0.0':54,62,131 '2gi':216,328,435,723 '3':112,249,626,800 '4':123,273,419,430,809 '4gi':329,418,599 '4o':240,512,622 '5':818 '8gi':434 'account':116,763 'account-level':115,762 'acr':96,98,111,732,755 'acrpul':107,737 'action':860 'add':438 'agent':3,8,22,30,37,69,85,182,194,197,202,245,251,257,262,275,280,285,303,338,361,372,391,443,554,558,573,576,581,631,642,648,672,677,697,701,705,725,813,822,837 'agent.name':246,632 'agent.state':640 'agent.version':248,287,636 'agentprotocol':178,368,550,667 'agentprotocol.responses':210,379,386,589,713,772 'ai':11,25,28,43,52,75,129,153,189,228,233,500,505,568,610,615,690,830 'aiprojectcli':145,149,172,185,544,564,661,686 'alloc':318,326,394 'alway':134 'applic':854 'ask':898 'async':649,668,673,679,684,704 'async-ag':703 'asynchron':678 'authent':133 'avail':335,382 'await':698 'azur':10,24,27,42,51,57,74,93,128,152,188,227,232,499,504,529,567,609,614,689,829,842 'azure-ai-project':50,127 'azure-ident':56 'azure.ai.projects':143,170,542 'azure.ai.projects.aio':659 'azure.ai.projects.models':174,365,546,663 'azure.identity':139,166,538 'azure.identity.aio':655 'b3':55,63,132 'base':21,35 'bash':47,73 'best':520,776 'block':817 'boundari':906 'build':6,32,89 'capabilityhostnotfound':756 'capabl':113,118,758,765 'caus':729 'clarif':900 'cleanup':819 'clear':873 'client':148,184,563,696 'client.agents.create':195,574,699 'client.agents.delete':278 'client.agents.list':255 'code':223,444,449,456,474,602 'common':726 'complet':532 'config':518 'configur':437,492,760,806 'contain':20,34,87,94,205,294,309,349,353,374,401,405,495,561,584,708,843 'container-bas':19,33 'core':158,416 'cpu':213,314,317,396,412,415,428,596,720 'cpu/memory':795 'creat':18,83,180,244,552,555,629,646,670,674,761 'creation':814 'credenti':146,156,157,192,571,683,693,694 'criteria':909 'custom':484,517,560 'custom-tool':483 'custom-tool.example.com':488 'data':579 'data-processor-ag':578 'def':551,669 'default':427 'defaultazurecredenti':136,141,147,168,193,540,572,657,681 'definit':203,403,582,706 'delet':274,820 'deni':735 'describ':861,877 'descript':293,385 'dict':332,341 'document':838 'e.g':319,327 'enablepublichostingenviron':121 'endpoint':77,150,155,186,191,230,235,502,507,565,570,612,617,687,692 'ensur':126 'environ':71,225,339,345,489,497,526,607,801,889 'environment-specif':888 'error':727,728,810 'exampl':533 'execut':856 'exist':753 'expert':894 'f':243,268,628,634,638 'file':477,605 'found':747 'foundri':26 'free':825 'full':308 'gib':420 'gpt':239,511,621 'gpt-4o-mini':238,510,620 'grant':101,736 'handl':811 'hardcod':523,808 'host':2,7,29,36,68,84,114,119,181,201,261,284,442,553,557,630,647,671,676,759,766,836 'hosted-agents-v2-py':1 'ident':58,106,743 'imag':88,217,305,310,408,562,592,716,745,749,781 'imagebasedhostedagentdefinit':15,39,176,204,288,404,548,583,665,707 'imagepullbackoff':731 'import':140,144,161,163,167,171,175,366,535,539,543,547,652,656,660,664 'info':516 'input':903 'instal':46,49 'interact':392 'interpret':224,445,450,457,475,603 'invalid':768 'invalidcontainerimag':744 'key':530 'label':461,482 'later':65 'latest':786 'learn.microsoft.com':840,846 'learn.microsoft.com/azure/ai-services/agents/how-to/hosted-agents)':839 'learn.microsoft.com/azure/container-registry/)':845 'level':117,515,764 'limit':423,865 'link':828 'list':250,297,331 'log':514 'main':645 'manag':105,742 'match':874 'max':426,624 'mcp':451,459,464,480 'memori':215,322,325,398,417,421,432,598,722 'min':425 'mini':241,513,623 'minim':790 'minimum':59,794 'miss':911 'model':236,508,618 'multipl':469 'my-hosted-ag':199,259,282 'my-mcp-serv':462 'my-mcp-server.example.com':468 'myregistry.azurecr.io':219,410,594,718 'myregistry.azurecr.io/async-agent:latest':717 'myregistry.azurecr.io/data-processor:v1.0':593 'myregistry.azurecr.io/my-agent:latest':218,409 'name':198,237,258,281,509,577,619,644,702 'need':799 'never':522,807 'os':164,536,653 'os.environ':151,187,231,503,566,613,688 'output':883 'overview':864 'paramet':289,290,356 'pass':491 'path':311,750 'pattern':650 'permiss':100,734,904 'pip':48 'practic':521,777 'prerequisit':81 'print':242,267,627,633,637 'processor':580 'product':788 'project':12,44,53,76,103,130,154,190,229,234,501,506,569,611,616,691,740,831 'protocol':206,209,295,300,350,354,359,370,375,378,383,384,389,406,585,588,709,712,769 'protocolversionnotsupport':767 'protocolversionrecord':177,208,298,367,377,549,587,666,711 'pull':99,733 'push':91 'py':5 'pypi.org':834 'pypi.org/project/azure-ai-projects/)':833 'python':31,137,162,183,253,277,363,402,446,453,471,496,534,651 'refer':827 'registri':95,844 'registry/image':312 'requir':66,292,902 'resourc':393,422,424,791,826 'respons':369,373,388 'retri':625 'return':641,724 'review':895 'role':108,738 'safeti':905 'scale':796 'scope':876 'sdk':13,45,60,124,832 'search':478,606 'secret':524 'server':460,465,466,481,486 'services.ai.azure.com':79 'services.ai.azure.com/api/projects/':78 'skill':852,868 'skill-hosted-agents-v2-py' 'solut':730 'source-sickn33' 'specif':783,890 'specifi':357,395 'standard':371,387 'start':792 'state':271,639 'stop':896 'str':306,315,323,342,343 'substitut':886 'success':908 'support':70,304,362 'tag':313,752,784 'task':872 'test':892 'tool':221,330,334,436,439,447,452,454,470,472,485,600 'topic-agent-skills' 'topic-agentic-skills' 'topic-ai-agent-skills' 'topic-ai-agents' 'topic-ai-coding' 'topic-ai-workflows' 'topic-antigravity' 'topic-antigravity-skills' 'topic-claude-code' 'topic-claude-code-skills' 'topic-codex-cli' 'topic-codex-skills' 'treat':881 'true':122 'try/except':816 'type':222,291,448,455,458,473,476,479,601,604 'unus':821 'url':467,487 'use':9,16,38,135,525,771,782,803,850,866 'v1':212,381,591,715,775 'v2':4 'valid':891 'valu':519 'variabl':72,226,340,346,490,498,527,608,802 'vault':531 'verifi':748 'version':61,125,196,207,211,247,252,254,256,264,266,269,276,279,286,296,301,351,355,376,380,407,575,586,590,635,700,710,714,770,774,779,823 'version.state':272 'version.version':270 'workflow':159,858 'wrap':812 'yes':299,307","prices":[{"id":"3cfa6afc-0fa3-4c2e-92ff-939048f5eb49","listingId":"50e02436-030a-4f52-a143-3df584521790","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"sickn33","category":"antigravity-awesome-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T21:38:37.646Z"}],"sources":[{"listingId":"50e02436-030a-4f52-a143-3df584521790","source":"github","sourceId":"sickn33/antigravity-awesome-skills/hosted-agents-v2-py","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/hosted-agents-v2-py","isPrimary":false,"firstSeenAt":"2026-04-18T21:38:37.646Z","lastSeenAt":"2026-04-23T18:51:28.344Z"}],"details":{"listingId":"50e02436-030a-4f52-a143-3df584521790","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"hosted-agents-v2-py","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34768,"topics":["agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity","antigravity-skills","claude-code","claude-code-skills","codex-cli","codex-skills","cursor","cursor-skills","developer-tools","gemini-cli","gemini-skills","kiro","mcp","skill-library"],"license":"mit","html_url":"https://github.com/sickn33/antigravity-awesome-skills","pushed_at":"2026-04-23T06:41:03Z","description":"Installable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.","skill_md_sha":"882fc387b1fc04ddb8e4df04913a934ad47b3feb","skill_md_path":"skills/hosted-agents-v2-py/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/hosted-agents-v2-py"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"hosted-agents-v2-py","description":"Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/hosted-agents-v2-py"},"updatedAt":"2026-04-23T18:51:28.344Z"}}