[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-17247fc6-4b00-47f1-bbb5-a6046d42197c":3,"$f9W5eq-YDYfgTum6wWNjxXjAy_y3-IgSfiW6O4Hot10Q":43},{"id":4,"title":5,"description":6,"categoryId":7,"moduleId":8,"tags":9,"prompt":10,"icon":11,"source":12,"sourceUrl":13,"authorId":14,"authorName":15,"isPublic":16,"stars":17,"runs":18,"createdAt":19,"updatedAt":19,"module":20,"category":27,"packages":34},"17247fc6-4b00-47f1-bbb5-a6046d42197c","hosted-agents-v2-py","使用Azure AI Projects SDK和ImageBasedHostedAgentDefinition构建托管代理。在Azure AI Foundry中创建基于容器的代理时使用。","cat_coding_devops","mod_coding","sickn33,coding","---\nname: hosted-agents-v2-py\ndescription: \"Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry.\"\nrisk: unknown\nsource: community\ndate_added: \"2026-02-27\"\n---\n\n# 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:\u002F\u002F\u003Cresource>.services.ai.azure.com\u002Fapi\u002Fprojects\u002F\u003Cproject>\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\u002Fmy-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\u002Fimage: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\u002Fmy-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:\u002F\u002Fmy-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:\u002F\u002Fcustom-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\u002Fdata-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\u002Fasync-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\u002Fmemory, scale up as needed\n3. **Environment Variables** - Use for all configuration, never hardcode\n4. **Error Handling** - Wrap agent creation in try\u002Fexcept blocks\n5. **Cleanup** - Delete unused agent versions to free resources\n\n## Reference Links\n\n- [Azure AI Projects SDK](https:\u002F\u002Fpypi.org\u002Fproject\u002Fazure-ai-projects\u002F)\n- [Hosted Agents Documentation](https:\u002F\u002Flearn.microsoft.com\u002Fazure\u002Fai-services\u002Fagents\u002Fhow-to\u002Fhosted-agents)\n- [Azure Container Registry](https:\u002F\u002Flearn.microsoft.com\u002Fazure\u002Fcontainer-registry\u002F)\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.\n","","imported","https:\u002F\u002Fgithub.com\u002Fsickn33\u002Fantigravity-awesome-skills","user_system_seed","SkillOPIC",true,63,1094,"2026-05-16 13:22:17",{"id":8,"name":21,"slug":22,"icon":23,"description":24,"sort":25,"createdAt":26},"编程开发","coding","mdi-code-braces","代码生成、调试、审查，提升开发效率",2,"2026-05-16 12:53:40",{"id":7,"name":28,"slug":29,"icon":30,"description":31,"moduleId":8,"sort":32,"skillCount":33,"createdAt":26},"DevOps","devops","mdi-cog-outline","CI\u002FCD、容器化、部署运维",3,162,[35],{"id":36,"skillId":4,"version":37,"fileName":38,"fileSize":39,"filePath":40,"fileHash":41,"manifest":42,"createdAt":19},"3a930200-6f9a-484d-824e-5ff048417934","1.0.0","hosted-agents-v2-py.zip",2974,"uploads\u002Fskills\u002F17247fc6-4b00-47f1-bbb5-a6046d42197c\u002Fhosted-agents-v2-py.zip","2d4e653f5c7818c09ee3815b1960b5e69b5b8a13d96d92b442e4f2f75a2ea238","[{\"path\":\"SKILL.md\",\"isDirectory\":false,\"size\":9518}]",{"code":44,"message":45,"data":46},200,"success",{"items":47,"stats":48,"page":51},[],{"averageRating":49,"totalRatings":49,"ratingCounts":50},0,[49,49,49,49,49],{"limit":52,"offset":49,"hasMore":53,"nextOffset":52,"ratedOnly":16},15,false]