{"id":"a678a8e2-f109-4368-a39e-bfd3d8a45434","shortId":"7Nf7ek","kind":"skill","title":"agents-v2-py","tagline":"Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images 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":["agents","antigravity","awesome","skills","sickn33","agent-skills","agentic-skills","ai-agent-skills","ai-agents","ai-coding","ai-workflows","antigravity-skills"],"capabilities":["skill","source-sickn33","skill-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/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 · 34964 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-25T00:50:24.164Z","embedding":null,"createdAt":"2026-04-18T21:30:36.899Z","updatedAt":"2026-04-25T00:50:24.164Z","lastSeenAt":"2026-04-25T00:50:24.164Z","tsv":"'/api/projects/':83 '/async-agent:latest':722 '/azure/ai-services/agents/how-to/hosted-agents)':844 '/azure/container-registry/)':850 '/data-processor:v1.0':598 '/my-agent:latest':223,414 '/project/azure-ai-projects/)':838 '0.5':432 '1':89,163,217,323,434,724,781 '1gi':436 '2':100,182,324,416,417,600,792 '2.0.0':57,65,134 '2gi':219,331,438,726 '3':115,252,629,803 '4':126,276,422,433,812 '4gi':332,421,602 '4o':243,515,625 '5':821 '8gi':437 'account':119,766 'account-level':118,765 'acr':99,101,114,735,758 'acrpul':110,740 'action':863 'add':441 'agent':2,10,21,33,40,72,88,185,197,200,205,248,254,260,265,278,283,288,306,341,364,375,394,446,557,561,576,579,584,634,645,651,675,680,700,704,708,728,816,825,840 'agent.name':249,635 'agent.state':643 'agent.version':251,290,639 'agentprotocol':181,371,553,670 'agentprotocol.responses':213,382,389,592,716,775 'agents-v2-py':1 'ai':13,28,31,46,55,78,132,156,192,231,236,503,508,571,613,618,693,833 'aiprojectcli':148,152,175,188,547,567,664,689 'alloc':321,329,397 'alway':137 'applic':857 'ask':901 'async':652,671,676,682,687,707 'async-ag':706 'asynchron':681 'authent':136 'avail':338,385 'await':701 'azur':12,27,30,45,54,60,77,96,131,155,191,230,235,502,507,532,570,612,617,692,832,845 'azure-ai-project':53,130 'azure-ident':59 'azure.ai.projects':146,173,545 'azure.ai.projects.aio':662 'azure.ai.projects.models':177,368,549,666 'azure.identity':142,169,541 'azure.identity.aio':658 'b3':58,66,135 'base':8,38 'bash':50,76 'best':523,779 'block':820 'boundari':909 'build':5,35,92 'capabilityhostnotfound':759 'capabl':116,121,761,768 'caus':732 'clarif':903 'cleanup':822 'clear':876 'client':151,187,566,699 'client.agents.create':198,577,702 'client.agents.delete':281 'client.agents.list':258 'code':226,447,452,459,477,605 'common':729 'complet':535 'config':521 'configur':440,495,763,809 'contain':7,24,37,90,97,208,297,312,352,356,377,404,408,498,564,587,711,846 'container-bas':6,36 'core':161,419 'cpu':216,317,320,399,415,418,431,599,723 'cpu/memory':798 'creat':19,86,183,247,555,558,632,649,673,677,764 'creation':817 'credenti':149,159,160,195,574,686,696,697 'criteria':912 'custom':23,487,520,563 'custom-tool':486 'custom-tool.example.com':491 'data':582 'data-processor-ag':581 'def':554,672 'default':430 'defaultazurecredenti':139,144,150,171,196,543,575,660,684 'definit':206,406,585,709 'delet':277,823 'deni':738 'describ':864,880 'descript':296,388 'dict':335,344 'document':841 'e.g':322,330 'enablepublichostingenviron':124 'endpoint':80,153,158,189,194,233,238,505,510,568,573,615,620,690,695 'ensur':129 'environ':74,228,342,348,492,500,529,610,804,892 'environment-specif':891 'error':730,731,813 'exampl':536 'execut':859 'exist':756 'expert':897 'f':246,271,631,637,641 'file':480,608 'found':750 'foundri':9,29 'free':828 'full':311 'gib':423 'gpt':242,514,624 'gpt-4o-mini':241,513,623 'grant':104,739 'handl':814 'hardcod':526,811 'host':20,32,39,71,87,117,122,184,204,264,287,445,556,560,633,650,674,679,762,769,839 'ident':61,109,746 'imag':25,91,220,308,313,411,565,595,719,748,752,784 'imagebasedhostedagentdefinit':16,42,179,207,291,407,551,586,668,710 'imagepullbackoff':734 'import':143,147,164,166,170,174,178,369,538,542,546,550,655,659,663,667 'info':519 'input':906 'instal':49,52 'interact':395 'interpret':227,448,453,460,478,606 'invalid':771 'invalidcontainerimag':747 'key':533 'label':464,485 'later':68 'latest':789 'learn.microsoft.com':843,849 'learn.microsoft.com/azure/ai-services/agents/how-to/hosted-agents)':842 'learn.microsoft.com/azure/container-registry/)':848 'level':120,518,767 'limit':426,868 'link':831 'list':253,300,334 'log':517 'main':648 'manag':108,745 'match':877 'max':429,627 'mcp':454,462,467,483 'memori':218,325,328,401,420,424,435,601,725 'min':428 'mini':244,516,626 'minim':793 'minimum':62,797 'miss':914 'model':239,511,621 'multipl':472 'my-hosted-ag':202,262,285 'my-mcp-serv':465 'my-mcp-server.example.com':471 'myregistry.azurecr.io':222,413,597,721 'myregistry.azurecr.io/async-agent:latest':720 'myregistry.azurecr.io/data-processor:v1.0':596 'myregistry.azurecr.io/my-agent:latest':221,412 'name':201,240,261,284,512,580,622,647,705 'need':802 'never':525,810 'os':167,539,656 'os.environ':154,190,234,506,569,616,691 'output':886 'overview':867 'paramet':292,293,359 'pass':494 'path':314,753 'pattern':653 'permiss':103,737,907 'pip':51 'practic':524,780 'prerequisit':84 'print':245,270,630,636,640 'processor':583 'product':791 'project':14,47,56,79,106,133,157,193,232,237,504,509,572,614,619,694,743,834 'protocol':209,212,298,303,353,357,362,373,378,381,386,387,392,409,588,591,712,715,772 'protocolversionnotsupport':770 'protocolversionrecord':180,211,301,370,380,552,590,669,714 'pull':102,736 'push':94 'py':4 'pypi.org':837 'pypi.org/project/azure-ai-projects/)':836 'python':34,140,165,186,256,280,366,405,449,456,474,499,537,654 'refer':830 'registri':98,847 'registry/image':315 'requir':69,295,905 'resourc':396,425,427,794,829 'respons':372,376,391 'retri':628 'return':644,727 'review':898 'role':111,741 'safeti':908 'scale':799 'scope':879 'sdk':15,48,63,127,835 'search':481,609 'secret':527 'server':463,468,469,484,489 'services.ai.azure.com':82 'services.ai.azure.com/api/projects/':81 'skill':855,871 'skill-agents-v2-py' 'solut':733 'source-sickn33' 'specif':786,893 'specifi':360,398 'standard':374,390 'start':795 'state':274,642 'stop':899 'str':309,318,326,345,346 'substitut':889 'success':911 'support':73,307,365 'tag':316,755,787 'task':875 'test':895 'tool':224,333,337,439,442,450,455,457,473,475,488,603 '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':884 'true':125 'try/except':819 'type':225,294,451,458,461,476,479,482,604,607 'unus':824 'url':470,490 'use':17,41,138,528,774,785,806,853,869 'v1':215,384,594,718,778 'v2':3 'valid':894 'valu':522 'variabl':75,229,343,349,493,501,530,611,805 'vault':534 'verifi':751 'version':64,128,199,210,214,250,255,257,259,267,269,272,279,282,289,299,304,354,358,379,383,410,578,589,593,638,703,713,717,773,777,782,826 'version.state':275 'version.version':273 'workflow':162,861 'wrap':815 'yes':302,310","prices":[{"id":"da175187-e3c1-4811-a10b-c3f2e09885ad","listingId":"a678a8e2-f109-4368-a39e-bfd3d8a45434","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:30:36.899Z"}],"sources":[{"listingId":"a678a8e2-f109-4368-a39e-bfd3d8a45434","source":"github","sourceId":"sickn33/antigravity-awesome-skills/agents-v2-py","sourceUrl":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/agents-v2-py","isPrimary":false,"firstSeenAt":"2026-04-18T21:30:36.899Z","lastSeenAt":"2026-04-25T00:50:24.164Z"}],"details":{"listingId":"a678a8e2-f109-4368-a39e-bfd3d8a45434","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"sickn33","slug":"agents-v2-py","github":{"repo":"sickn33/antigravity-awesome-skills","stars":34964,"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-24T06:41:17Z","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":"9ba6bdb2f0d4407de2803f8049ef2b2d45277e8b","skill_md_path":"skills/agents-v2-py/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/agents-v2-py"},"layout":"multi","source":"github","category":"antigravity-awesome-skills","frontmatter":{"name":"agents-v2-py","description":"Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry."},"skills_sh_url":"https://skills.sh/sickn33/antigravity-awesome-skills/agents-v2-py"},"updatedAt":"2026-04-25T00:50:24.164Z"}}