Agents V2 Py

1---
2name: agents-v2-py
3description: |
4  Build container-based Foundry Agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition.
5  Use when creating hosted agents that run custom code in Azure AI Foundry with your own container images.
6  Triggers: "ImageBasedHostedAgentDefinition", "hosted agent", "container agent", "Foundry Agent",
7  "create_version", "ProtocolVersionRecord", "AgentProtocol.RESPONSES", "custom agent image".
8package: azure-ai-projects
9---
10 
11# Azure AI Hosted Agents (Python)
12 
13Build container-based hosted agents using `ImageBasedHostedAgentDefinition` from the Azure AI Projects SDK.
14 
15## Installation
16 
17```bash
18pip install azure-ai-projects>=2.0.0b3 azure-identity
19```
20 
21**Minimum SDK Version:** `2.0.0b3` or later required for hosted agent support.
22 
23## Environment Variables
24 
25```bash
26AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
27```
28 
29## Prerequisites
30 
31Before creating hosted agents:
32 
331. **Container Image** - Build and push to Azure Container Registry (ACR)
342. **ACR Pull Permissions** - Grant your project's managed identity `AcrPull` role on the ACR
353. **Capability Host** - Account-level capability host with `enablePublicHostingEnvironment=true`
364. **SDK Version** - Ensure `azure-ai-projects>=2.0.0b3`
37 
38## Authentication
39 
40Always use `DefaultAzureCredential`:
41 
42```python
43from azure.identity import DefaultAzureCredential
44from azure.ai.projects import AIProjectClient
45 
46credential = DefaultAzureCredential()
47client = AIProjectClient(
48    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
49    credential=credential
50)
51```
52 
53## Core Workflow
54 
55### 1. Imports
56 
57```python
58import os
59from azure.identity import DefaultAzureCredential
60from azure.ai.projects import AIProjectClient
61from azure.ai.projects.models import (
62    ImageBasedHostedAgentDefinition,
63    ProtocolVersionRecord,
64    AgentProtocol,
65)
66```
67 
68### 2. Create Hosted Agent
69 
70```python
71client = AIProjectClient(
72    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
73    credential=DefaultAzureCredential()
74)
75 
76agent = client.agents.create_version(
77    agent_name="my-hosted-agent",
78    definition=ImageBasedHostedAgentDefinition(
79        container_protocol_versions=[
80            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
81        ],
82        cpu="1",
83        memory="2Gi",
84        image="myregistry.azurecr.io/my-agent:latest",
85        tools=[{"type": "code_interpreter"}],
86        environment_variables={
87            "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
88            "MODEL_NAME": "gpt-4o-mini"
89        }
90    )
91)
92 
93print(f"Created agent: {agent.name} (version: {agent.version})")
94```
95 
96### 3. List Agent Versions
97 
98```python
99versions = client.agents.list_versions(agent_name="my-hosted-agent")
100for version in versions:
101    print(f"Version: {version.version}, State: {version.state}")
102```
103 
104### 4. Delete Agent Version
105 
106```python
107client.agents.delete_version(
108    agent_name="my-hosted-agent",
109    version=agent.version
110)
111```
112 
113## ImageBasedHostedAgentDefinition Parameters
114 
115| Parameter | Type | Required | Description |
116|-----------|------|----------|-------------|
117| `container_protocol_versions` | `list[ProtocolVersionRecord]` | Yes | Protocol versions the agent supports |
118| `image` | `str` | Yes | Full container image path (registry/image:tag) |
119| `cpu` | `str` | No | CPU allocation (e.g., "1", "2") |
120| `memory` | `str` | No | Memory allocation (e.g., "2Gi", "4Gi") |
121| `tools` | `list[dict]` | No | Tools available to the agent |
122| `environment_variables` | `dict[str, str]` | No | Environment variables for the container |
123 
124## Protocol Versions
125 
126The `container_protocol_versions` parameter specifies which protocols your agent supports:
127 
128```python
129from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
130 
131# RESPONSES protocol - standard agent responses
132container_protocol_versions=[
133    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
134]
135```
136 
137**Available Protocols:**
138| Protocol | Description |
139|----------|-------------|
140| `AgentProtocol.RESPONSES` | Standard response protocol for agent interactions |
141 
142## Resource Allocation
143 
144Specify CPU and memory for your container:
145 
146```python
147definition=ImageBasedHostedAgentDefinition(
148    container_protocol_versions=[...],
149    image="myregistry.azurecr.io/my-agent:latest",
150    cpu="2",      # 2 CPU cores
151    memory="4Gi"  # 4 GiB memory
152)
153```
154 
155**Resource Limits:**
156| Resource | Min | Max | Default |
157|----------|-----|-----|---------|
158| CPU | 0.5 | 4 | 1 |
159| Memory | 1Gi | 8Gi | 2Gi |
160 
161## Tools Configuration
162 
163Add tools to your hosted agent:
164 
165### Code Interpreter
166 
167```python
168tools=[{"type": "code_interpreter"}]
169```
170 
171### MCP Tools
172 
173```python
174tools=[
175    {"type": "code_interpreter"},
176    {
177        "type": "mcp",
178        "server_label": "my-mcp-server",
179        "server_url": "https://my-mcp-server.example.com"
180    }
181]
182```
183 
184### Multiple Tools
185 
186```python
187tools=[
188    {"type": "code_interpreter"},
189    {"type": "file_search"},
190    {
191        "type": "mcp",
192        "server_label": "custom-tool",
193        "server_url": "https://custom-tool.example.com"
194    }
195]
196```
197 
198## Environment Variables
199 
200Pass configuration to your container:
201 
202```python
203environment_variables={
204    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
205    "MODEL_NAME": "gpt-4o-mini",
206    "LOG_LEVEL": "INFO",
207    "CUSTOM_CONFIG": "value"
208}
209```
210 
211**Best Practice:** Never hardcode secrets. Use environment variables or Azure Key Vault.
212 
213## Complete Example
214 
215```python
216import os
217from azure.identity import DefaultAzureCredential
218from azure.ai.projects import AIProjectClient
219from azure.ai.projects.models import (
220    ImageBasedHostedAgentDefinition,
221    ProtocolVersionRecord,
222    AgentProtocol,
223)
224 
225def create_hosted_agent():
226    """Create a hosted agent with custom container image."""
227    
228    client = AIProjectClient(
229        endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
230        credential=DefaultAzureCredential()
231    )
232    
233    agent = client.agents.create_version(
234        agent_name="data-processor-agent",
235        definition=ImageBasedHostedAgentDefinition(
236            container_protocol_versions=[
237                ProtocolVersionRecord(
238                    protocol=AgentProtocol.RESPONSES,
239                    version="v1"
240                )
241            ],
242            image="myregistry.azurecr.io/data-processor:v1.0",
243            cpu="2",
244            memory="4Gi",
245            tools=[
246                {"type": "code_interpreter"},
247                {"type": "file_search"}
248            ],
249            environment_variables={
250                "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
251                "MODEL_NAME": "gpt-4o-mini",
252                "MAX_RETRIES": "3"
253            }
254        )
255    )
256    
257    print(f"Created hosted agent: {agent.name}")
258    print(f"Version: {agent.version}")
259    print(f"State: {agent.state}")
260    
261    return agent
262 
263if __name__ == "__main__":
264    create_hosted_agent()
265```
266 
267## Async Pattern
268 
269```python
270import os
271from azure.identity.aio import DefaultAzureCredential
272from azure.ai.projects.aio import AIProjectClient
273from azure.ai.projects.models import (
274    ImageBasedHostedAgentDefinition,
275    ProtocolVersionRecord,
276    AgentProtocol,
277)
278 
279async def create_hosted_agent_async():
280    """Create a hosted agent asynchronously."""
281    
282    async with DefaultAzureCredential() as credential:
283        async with AIProjectClient(
284            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
285            credential=credential
286        ) as client:
287            agent = await client.agents.create_version(
288                agent_name="async-agent",
289                definition=ImageBasedHostedAgentDefinition(
290                    container_protocol_versions=[
291                        ProtocolVersionRecord(
292                            protocol=AgentProtocol.RESPONSES,
293                            version="v1"
294                        )
295                    ],
296                    image="myregistry.azurecr.io/async-agent:latest",
297                    cpu="1",
298                    memory="2Gi"
299                )
300            )
301            return agent
302```
303 
304## Common Errors
305 
306| Error | Cause | Solution |
307|-------|-------|----------|
308| `ImagePullBackOff` | ACR pull permission denied | Grant `AcrPull` role to project's managed identity |
309| `InvalidContainerImage` | Image not found | Verify image path and tag exist in ACR |
310| `CapabilityHostNotFound` | No capability host configured | Create account-level capability host |
311| `ProtocolVersionNotSupported` | Invalid protocol version | Use `AgentProtocol.RESPONSES` with version `"v1"` |
312 
313## Best Practices
314 
3151. **Version Your Images** - Use specific tags, not `latest` in production
3162. **Minimal Resources** - Start with minimum CPU/memory, scale up as needed
3173. **Environment Variables** - Use for all configuration, never hardcode
3184. **Error Handling** - Wrap agent creation in try/except blocks
3195. **Cleanup** - Delete unused agent versions to free resources
320 
321## Reference Links
322 
323- [Azure AI Projects SDK](https://pypi.org/project/azure-ai-projects/)
324- [Hosted Agents Documentation](https://learn.microsoft.com/azure/ai-services/agents/how-to/hosted-agents)
325- [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/)
326