Was macht Azure AI Gehostete Agents (Python)?
Erstellen Sie containerbasierte, gehostete Agents mit ImageBasedHostedAgentDefinition aus dem Azure AI Projects SDK.
Installation
pip install azure-ai-projects>=2.0.0b3 azure-identity
Mindest-SDK-Version: 2.0.0b3 oder höher erforderlich für die Unterstützung gehosteter Agents.
Umgebungsvariablen
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
Voraussetzungen
Bevor Sie gehostete Agents erstellen:
- Container-Image – Erstellen und veröffentlichen Sie es in einer Azure Container Registry (ACR)
- ACR Pull-Berechtigungen – Weisen Sie der verwalteten Identität Ihres Projekts die Rolle
AcrPullauf der ACR zu - Capability Host – Capability Host auf Kontoebene mit
enablePublicHostingEnvironment=true - SDK-Version – Stellen Sie sicher, dass
azure-ai-projects>=2.0.0b3installiert ist
Authentifizierung
Verwenden Sie immer DefaultAzureCredential:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
credential = DefaultAzureCredential()
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
)
Kern-Workflow
1. Importe
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
2. Gehosteten Agent erstellen
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="my-hosted-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
],
cpu="1",
memory="2Gi",
image="myregistry.azurecr.io/my-agent:latest",
tools=[{"type": "code_interpreter"}],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini"
}
)
)
print(f"Erstellter Agent: {agent.name} (Version: {agent.version})")
3. Agent-Versionen auflisten
versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
print(f"Version: {version.version}, Status: {version.state}")
4. Agent-Version löschen
client.agents.delete_version(
agent_name="my-hosted-agent",
version=agent.version
)
Parameter von ImageBasedHostedAgentDefinition
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
container_protocol_versions | list[ProtocolVersionRecord] | Ja | Vom Agent unterstützte Protokollversionen |
image | str | Ja | Vollständiger Container-Image-Pfad (Registry/Image:Tag) |
cpu | str | Nein | CPU-Zuweisung (z. B. "1", "2") |
memory | str | Nein | Arbeitsspeicherzuweisung (z. B. "2Gi", "4Gi") |
tools | list[dict] | Nein | Dem Agent verfügbare Tools |
environment_variables | dict[str, str] | Nein | Umgebungsvariablen für den Container |
Protokollversionen
Der Parameter container_protocol_versions gibt an, welche Protokolle Ihr Agent unterstützt:
from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
# RESPONSES-Protokoll – Standard-Agent-Antworten
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]
Verfügbare Protokolle:
| Protokoll | Beschreibung |
|---|---|
AgentProtocol.RESPONSES | Standard-Antwortprotokoll für Agent-Interaktionen |
Ressourcenzuweisung
Geben Sie CPU und Arbeitsspeicher für Ihren Container an:
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[...],
image="myregistry.azurecr.io/my-agent:latest",
cpu="2", # 2 CPU-Kerne
memory="4Gi" # 4 GiB Arbeitsspeicher
)
Ressourcengrenzen:
| Ressource | Min | Max | Standard |
|---|---|---|---|
| CPU | 0,5 | 4 | 1 |
| Arbeitsspeicher | 1Gi | 8Gi | 2Gi |
Tool-Konfiguration
Fügen Sie Ihrem gehosteten Agent Tools hinzu:
Code-Interpreter
tools=[{"type": "code_interpreter"}]
MCP-Tools
tools=[
{"type": "code_interpreter"},
{
"type": "mcp",
"server_label": "my-mcp-server",
"server_url": "https://my-mcp-server.example.com"
}
]
Mehrere Tools
tools=[
{"type": "code_interpreter"},
{"type": "file_search"},
{
"type": "mcp",
"server_label": "custom-tool",
"server_url": "https://custom-tool.example.com"
}
]
Umgebungsvariablen
Übergeben Sie Konfiguration an Ihren Container:
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini",
"LOG_LEVEL": "INFO",
"CUSTOM_CONFIG": "value"
}
Bewährte Methode: Härten Sie Geheimnisse niemals fest ein. Verwenden Sie Umgebungsvariablen oder Azure Key Vault.
Vollständiges Beispiel
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
def create_hosted_agent():
"""Erstellt einen gehosteten Agent mit einem benutzerdefinierten Container-Image."""
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="data-processor-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1"
)
],
image="myregistry.azurecr.io/data-processor:v1.0",
cpu="2",
memory="4Gi",
tools=[
{"type": "code_interpreter"},
{"type": "file_search"}
],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini",
"MAX_RETRIES": "3"
}
)
)
print(f"Erstellter gehosteter Agent: {agent.name}")
print(f"Version: {agent.version}")
print(f"Status: {agent.state}")
return agent
if __name__ == "__main__":
create_hosted_agent()
Asynchrones Muster
import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
async def create_hosted_agent_async():
"""Erstellt einen gehosteten Agent asynchron."""
async with DefaultAzureCredential() as credential:
async with AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
) as client:
agent = await client.agents.create_version(
agent_name="async-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(
protocol=AgentProtocol.RESPONSES,
version="v1"
)
],
image="myregistry.azurecr.io/async-agent:latest",
cpu="1",
memory="2Gi"
)
)
return agent
Häufige Fehler
| Fehler | Ursache | Lösung |
|---|---|---|
ImagePullBackOff | ACR Pull-Berechtigung verweigert | Weisen Sie der verwalteten Identität des Projekts die Rolle AcrPull zu |
InvalidContainerImage | Image nicht gefunden | Überprüfen Sie, ob Image-Pfad und Tag in der ACR existieren |
CapabilityHostNotFound | Kein Capability Host konfiguriert | Erstellen Sie einen Capability Host auf Kontoebene |
ProtocolVersionNotSupported | Ungültige Protokollversion | Verwenden Sie AgentProtocol.RESPONSES mit der Version "v1" |
Bewährte Methoden
- Images versionieren – Verwenden Sie in der Produktion spezifische Tags, nicht
latest - Minimale Ressourcen – Beginnen Sie mit minimaler CPU/Arbeitsspeicher und skalieren Sie bei Bedarf hoch
- Umgebungsvariablen – Verwenden Sie diese für die gesamte Konfiguration; härten Sie nichts fest ein
- Fehlerbehandlung – Umgeben Sie die Agent-Erstellung mit try/except-Blöcken
- Bereinigung – Löschen Sie nicht verwendete Agent-Versionen, um Ressourcen freizugeben
Referenzlinks
Wann verwenden
Diese Fähigkeit ist anwendbar, um den in der Übersicht beschriebenen Workflow oder die darin beschriebenen Aktionen auszuführen.
Einschränkungen
- Verwenden Sie diese Fähigkeit nur, wenn die Aufgabe eindeutig dem oben beschriebenen Umfang entspricht.
- Behandeln Sie die Ausgabe nicht als Ersatz für eine umgebungsspezifische Validierung, Tests oder eine fachliche Überprüfung.
- Halten Sie an und fragen Sie nach, wenn erforderliche Eingaben, Berechtigungen, Sicherheitsgrenzen oder Erfolgskriterien fehlen.