Agent Framework Azure Gehostete Agents
Erstelle persistente Agents auf Azure AI Foundry mit dem Microsoft Agent Framework Python SDK.
Architektur
Benutzeranfrage → AzureAIAgentsProvider → Azure AI Agent Service (Persistent)
↓
Agent.run() / Agent.run_stream()
↓
Tools: Funktionen | Gehostet (Code/Suche/Web) | MCP
↓
AgentThread (Konversationspersistenz)
Installation
# Vollständiges Framework (empfohlen)
pip install agent-framework --pre
# Oder nur Azure-spezifisches Paket
pip install agent-framework-azure-ai --pre
Umgebungsvariablen
export AZURE_AI_PROJECT_ENDPOINT="https://<project>.services.ai.azure.com/api/projects/<project-id>" # Erforderlich für alle Authentifizierungsmethoden
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini" # Erforderlich für alle Authentifizierungsmethoden
export BING_CONNECTION_ID="your-bing-connection-id" # Für Websuche
export AZURE_TOKEN_CREDENTIALS=prod # Nur erforderlich, wenn DefaultAzureCredential in der Produktion verwendet wird
Authentifizierung & Lebenszyklus
🔑 Zwei Regeln gelten für jedes untenstehende Codebeispiel:
- Bevorzuge
DefaultAzureCredential. Es funktioniert lokal (Azure CLI / VS Code / Developer CLI) und in Azure (Managed Identity, Workload Identity) ohne Codeänderung. Vermeide Verbindungszeichenfolgen, Konto-/API-Schlüssel – sie umgehen Entra-Überprüfung und Rotation.
- Lokale Entwicklung:
DefaultAzureCredentialfunktioniert sofort.- Produktion: Setze
AZURE_TOKEN_CREDENTIALS=prod(oderAZURE_TOKEN_CREDENTIALS=<spezifische_anmeldeinformation>), um die Anmeldeinformationskette auf produktionssichere Anmeldeinformationen zu beschränken.- Wickle jeden Client in einen Kontextmanager ein, damit HTTP-Transports, Sockets und Token-Caches deterministisch freigegeben werden:
- Synchron:
with <Client>(...) as client:- Asynchron:
async with <Client>(...) as client:undasync with DefaultAzureCredential() as credential:(ausazure.identity.aio)Codeausschnitte können diesen Aufbau verkürzen, aber Produktionscode sollte immer beiden Regeln folgen.
from azure.identity.aio import AzureCliCredential, DefaultAzureCredential, ManagedIdentityCredential
# Entwicklung
credential = AzureCliCredential()
# Produktion
# Lokale Entwicklung: DefaultAzureCredential. Produktion: Setze AZURE_TOKEN_CREDENTIALS=prod oder AZURE_TOKEN_CREDENTIALS=<spezifische_anmeldeinformation>
credential = DefaultAzureCredential(require_envvar=True)
# Oder verwende direkt spezifische Anmeldeinformationen in der Produktion:
# Siehe https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()
Kern-Workflow
Basis-Agent
import asyncio
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="MyAgent",
instructions="Du bist ein hilfreicher Assistent.",
)
result = await agent.run("Hallo!")
print(result.text)
asyncio.run(main())
Agent mit Funktions-Tools
from typing import Annotated
from pydantic import Field
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
def get_weather(
location: Annotated[str, Field(description="Stadtname, für den das Wetter abgerufen werden soll")],
) -> str:
"""Holt das aktuelle Wetter für einen Ort."""
return f"Wetter in {location}: 72°F, sonnig"
def get_current_time() -> str:
"""Holt die aktuelle UTC-Zeit."""
from datetime import datetime, timezone
return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="WeatherAgent",
instructions="Du hilfst bei Wetter- und Zeitanfragen.",
tools=[get_weather, get_current_time], # Funktionen direkt übergeben
)
result = await agent.run("Wie ist das Wetter in Seattle?")
print(result.text)
Agent mit gehosteten Tools
from agent_framework import (
HostedCodeInterpreterTool,
HostedFileSearchTool,
HostedWebSearchTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="MultiToolAgent",
instructions="Du kannst Code ausführen, Dateien durchsuchen und das Web durchsuchen.",
tools=[
HostedCodeInterpreterTool(),
HostedWebSearchTool(name="Bing"),
],
)
result = await agent.run("Berechne die Fakultät von 20 in Python")
print(result.text)
Streamende Antworten
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="StreamingAgent",
instructions="Du bist ein hilfreicher Assistent.",
)
print("Agent: ", end="", flush=True)
async for chunk in agent.run_stream("Erzähl mir eine kurze Geschichte"):
if chunk.text:
print(chunk.text, end="", flush=True)
print()
Konversationsthreads
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="ChatAgent",
instructions="Du bist ein hilfreicher Assistent.",
tools=[get_weather],
)
# Thread für Konversationspersistenz erstellen
thread = agent.get_new_thread()
# Erste Runde
result1 = await agent.run("Wie ist das Wetter in Seattle?", thread=thread)
print(f"Agent: {result1.text}")
# Zweite Runde - Kontext bleibt erhalten
result2 = await agent.run("Und was ist mit Portland?", thread=thread)
print(f"Agent: {result2.text}")
# Thread-ID für späteren Wiederaufnahme speichern
print(f"Konversations-ID: {thread.conversation_id}")
Strukturierte Ausgaben
from pydantic import BaseModel, ConfigDict
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
class WeatherResponse(BaseModel):
model_config = ConfigDict(extra="forbid")
location: str
temperature: float
unit: str
conditions: str
async def main():
async with (
AzureCliCredential() as credential,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="StructuredAgent",
instructions="Gib Wetterinformationen in strukturiertem Format aus.",
response_format=WeatherResponse,
)
result = await agent.run("Wetter in Seattle?")
weather = WeatherResponse.model_validate_json(result.text)
print(f"{weather.location}: {weather.temperature}°{weather.unit}")
Provider-Methoden
| Methode | Beschreibung |
|---|---|
create_agent() | Neuen Agenten im Azure AI Service erstellen |
get_agent(agent_id) | Vorhandenen Agenten anhand der ID abrufen |
as_agent(sdk_agent) | SDK-Agentenobjekt wrappen (kein HTTP-Aufruf) |
Kurzübersicht gehostete Tools
| Tool | Import | Zweck |
|---|---|---|
HostedCodeInterpreterTool | from agent_framework import HostedCodeInterpreterTool | Python-Code ausführen |
HostedFileSearchTool | from agent_framework import HostedFileSearchTool | Vektorspeicher durchsuchen |
HostedWebSearchTool | from agent_framework import HostedWebSearchTool | Bing-Websuche |
HostedMCPTool | from agent_framework import HostedMCPTool | Dienstseitig verwaltetes MCP |
MCPStreamableHTTPTool | from agent_framework import MCPStreamableHTTPTool | Clientseitig verwaltetes MCP |
Vollständiges Beispiel
import asyncio
from typing import Annotated
from pydantic import BaseModel, Field
from agent_framework import (
HostedCodeInterpreterTool,
HostedWebSearchTool,
MCPStreamableHTTPTool,
)
from agent_framework.azure import AzureAIAgentsProvider
from azure.identity.aio import AzureCliCredential
def get_weather(
location: Annotated[str, Field(description="Stadtname")],
) -> str:
"""Holt das Wetter für einen Ort."""
return f"Wetter in {location}: 72°F, sonnig"
class AnalysisResult(BaseModel):
summary: str
key_findings: list[str]
confidence: float
async def main():
async with (
AzureCliCredential() as credential,
MCPStreamableHTTPTool(
name="Docs MCP",
url="https://learn.microsoft.com/api/mcp",
) as mcp_tool,
AzureAIAgentsProvider(credential=credential) as provider,
):
agent = await provider.create_agent(
name="ResearchAssistant",
instructions="Du bist ein Forschungsassistent mit mehreren Fähigkeiten.",
tools=[
get_weather,
HostedCodeInterpreterTool(),
HostedWebSearchTool(name="Bing"),
mcp_tool,
],
)
thread = agent.get_new_thread()
# Nicht-streamend
result = await agent.run(
"Suche nach Python-Best Practices und fasse zusammen",
thread=thread,
)
print(f"Antwort: {result.text}")
# Streamend
print("\nStreamend: ", end="")
async for chunk in agent.run_stream("Fahre mit Beispielen fort", thread=thread):
if chunk.text:
print(chunk.text, end="", flush=True)
print()
# Strukturierte Ausgabe
result = await agent.run(
"Analysiere die Ergebnisse",
thread=thread,
response_format=AnalysisResult,
)
analysis = AnalysisResult.model_validate_json(result.text)
print(f"\nKonfidenz: {analysis.confidence}")
if __name__ == "__main__":
asyncio.run(main())
Konventionen
- Verwende immer async-Kontextmanager:
async with provider: - Übergebe Funktionen direkt an den Parameter
tools=(automatisch in AIFunction konvertiert) - Verwende
Annotated[type, Field(description=...)]für Funktionsparameter - Verwende
get_new_thread()für Mehrfachgespräche - Bevorzuge
HostedMCPToolfür dienstseitig verwaltetes MCP,MCPStreamableHTTPToolfür clientseitig verwaltetes MCP
Best Practices
- Dieses SDK ist async-first – verwende
async def-Handler und überallasync with. - Verwende immer Kontextmanager für Clients und async-Anmeldeinformationen. Wickle jeden Client in
with Client(...) as client:(synchron) oderasync with Client(...) as client:(asynchron) ein. Für asyncDefaultAzureCredentialausazure.identity.aioverwende ebenfallsasync with credential:, damit Tokens und Transports bereinigt werden.
Referenzdateien
- references/tools.md: Detaillierte gehostete Tool-Muster
- references/mcp.md: MCP-Integration (gehostet + lokal)
- references/threads.md: Thread- und Konversationsverwaltung
- references/advanced.md: OpenAPI, Zitate, strukturierte Ausgaben