Microsoft Foundry-Agentendienst

Installieren der Pakete

dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

Herstellen einer Verbindung mit einem Eingabeaufforderungs-Agent

Erstellen Sie ein AIProjectClient Projekt für das Foundry-Projekt, und umschließen Sie es AgentReference als ein FoundryAgent. Pin the version when the application must use a specific Prompt Agent definition.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI.Foundry;

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

Sie können auch eine ProjectsAgentRecord abrufen, um die neueste Version oder eine ProjectsAgentVersion explizit abgerufene Version zu verwenden, und dieses Objekt dann an projectClient.AsAIAgent(...)übergeben.

Abrufen der neuesten Prompt Agent-Version

Wird verwendet AgentAdministrationClient , wenn die Anwendung die neueste registrierte Version anhand des Namens auflösen soll.

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Herstellen einer Verbindung mit einem gehosteten Agent

Gehostete Agents machen einen agentspezifischen OpenAI-Endpunkt verfügbar. Erstellen Sie den Endpunkt vom Projektendpunkt und dem Namen des registrierten Agents, und übergeben Sie ihn an AIProjectClient.AsAIAgent(...).

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

Die vom Administrator kontrollierte Versionsauswahl des Endpunkts bestimmt die aktive Version des gehosteten Agents.

Installieren der Pakete

pip install agent-framework-foundry

Configuration

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

Verwenden Sie FOUNDRY_AGENT_VERSION für Prompt-Agents. Gehostete Agents können sie weglassen.

Herstellen einer Verbindung mit einem Eingabeaufforderungs-Agent

Geben Sie den Projektendpunkt, den Agentnamen und die Agentversion an. Der Dienst stellt das gespeicherte Modell, die Anweisungen und die Konfiguration des gehosteten Tools bereit.

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Streaming
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Wenn ein Eingabeaufforderungs-Agent ein lokales Funktionstool deklariert, übergeben Sie den übereinstimmenden Aufruf tools= beim Erstellen FoundryAgent , damit der Client es bei Bedarf ausführen kann. Sehen Sie sich das Beispiel zum Veröffentlichen und Verbinden des Eingabeaufforderungs-Agents an.

Herstellen einer Verbindung mit einem gehosteten Agent

Gehostete Agents benötigen agent_versionkeine . Stellen Sie eine Verbindung mit dem Projektendpunkt und dem Namen des registrierten Agents her.

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

Was funktioniert und was nicht? FoundryAgent

FoundryAgent stellt eine Verbindung mit einer Agentdefinition her, die bereits in Foundry vorhanden ist. Die gespeicherten Anweisungen und die Toolkonfiguration sind autoritativ, sodass sich das clientseitige Verhalten von einer Anwendung Agent(client=FoundryChatClient(...))unterscheidet.

Tools

Anleitungen für die Toolbox-Anlage und den direkten MCP-Verbrauch finden Sie unter Microsoft Foundry Toolbox.

Sie können zum Bauzeit kein neues modell sichtbares Werkzeug registrieren. Das Übergeben einer funktion aufrufbaren Funktion liefert nur die lokale Implementierung für eine Funktion, die der Foundry-Agent bereits deklariert.

Kontextanbieter

Wird verwendet Agent(client=FoundryChatClient(...)) , wenn die Anwendung dynamische Toolauswahl, Fähigkeitsladefähigkeit oder jedes Verhalten benötigt, das modell sichtbare Tools zur Laufzeit ändert.

Ausführungsoptionen

Da die Definition des Foundry-Agenten die Quelle der Wahrheit ist, wird nicht jede Option durchgegangen default_options oder agent.run(...) berücksichtigt.

Gehostete Agents erhalten dieselbe clientseitige Filterung, aber der bereitgestellte Agent kann jede weitergeleitete Option akzeptieren, ignorieren oder erneut interpretieren. Überprüfen Sie das Verhalten für den bestimmten gehosteten Agent.

Verwalten einer Gehosteten Agent-Dienstsitzung

Für gehostete Agents, die dienstseitige Sitzungen verwenden, ist die Vorschauantwortoberfläche erforderlich:

Erstellen Sie die Dienstsitzung explizit, wenn die Anwendung sie an einen Mandanten oder Benutzer binden muss, und schließen Sie den Bezeichner dann als Agent Framework-Sitzung um.

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Festlegen eines benutzerdefinierten HTTP-Timeouts

FoundryAgent erbt standardmäßig das OpenAI SDK-Timeout. Übergeben Sie timeout= Sekunden, wenn mehrstufige Unterhaltungen oder Netzwerkbedingungen ein anderes Limit erfordern.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

Das Timeout wird auf eine Kopie pro Agent des HTTP-Clients angewendet und wirkt sich nicht auf andere Agents aus, die dasselbe AIProjectClientverwenden.