Microsoft Foundry-Agentendienst

FoundryAgentstellt agent Framework mit einer von Microsoft Foundry Agent Service verwalteten Agentdefinition her. Das Modell, anweisungen, gehostete Tools und Die Version des Agents werden in Foundry konfiguriert; Ihre Anwendung stellt eine Verbindung mit dieser Definition und verwendet die standardmäßigen Agent Framework-Ausführungs-, Streaming- und Sitzungs-APIs.

Verwenden Sie diese Integration für:

• Eingabeaufforderungs-Agents, die benannte und versionsgesteuerte serverseitige Agentdefinitionen sind.
• Gehostete Agents, die bereitgestellte Agentanwendungen über einen agentspezifischen Endpunkt erreicht werden.

Eine direkte Modellreferenz, in der Ihre Anwendung die Agentdefinition besitzt, finden Sie unter Microsoft Foundry-Modellanbieter. Informationen zum Bereitstellen einer Agent Framework-Anwendung als gehosteter Agent finden Sie unter Foundry Hosted Agents.

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?"));

Important

A FoundryAgent verwendet das Modell, die Anweisungen und gehosteten Tools, die in ihrer Foundry-Definition gespeichert sind. Konfigurieren Sie diese Funktionen in Foundry; der Client kann sie zur Laufzeit nicht ersetzen.

Warning

DefaultAzureCredential ist praktisch für die Entwicklung. Bevorzugen Sie in der Produktion eine bestimmte Anmeldeinformation, z ManagedIdentityCredential . B. um unbeabsichtigte Anmeldeinformationen zu vermeiden.

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

An den Tooltyp übergeben FoundryAgent(...)	Behavior
FunctionToolmit einem lokalen Python aufrufbar	Wird nur unterstützt, wenn die übereinstimmende Funktionsdefinition bereits im Foundry-Agent vorhanden ist. Die Aufrufbare wird im Anwendungsprozess ausgeführt, wenn Foundry sie anfordert.
Gehostete Tools, einschließlich Websuche, Codedolmetscher, Dateisuche, MCP, Bildgenerierung und Microsoft Foundry Toolbox	Konfigurieren Sie diese in der Definition des Foundry-Agents. Das Übergeben clientseitiger Elemente fügt sie nicht zum vom Dienst verwalteten Agent hinzu.

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

Verhalten des Kontextanbieters	Funktioniert mit FoundryAgent?
Fügt Nachrichten hinzu, z. B. abgerufenen Speicher, RAG-Codeausschnitte oder Benutzerprofilinformationen	Yes. Der eingefügte Kontext wird mit der Anforderung weitergeleitet.
Behält die Unterhaltung bei oder beobachtet sie.	Yes. Der Anbieter wird lokal um die Anforderung und Antwort herum ausgeführt.
Dynamisches Hinzufügen von Tools	Nein, es sei denn, diese Tools werden bereits in der Definition des Foundry-Agents deklariert.

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.

Auswahl	Verhalten des Eingabeaufforderungs-Agents
model	Ignoriert. Das Modell stammt aus der Definition des Foundry-Agents.
tools, tool_choiceparallel_tool_calls	Aus der Anforderung entfernt. Tools müssen in der Definition des Foundry-Agents deklariert werden.
instructions und System- oder Entwicklernachrichten	Ignoriert. Die gespeicherten Foundry-Anweisungen sind autoritativ.
conversation_id	Wird bei Bedarf der Foundry-Agent-Sitzung verwendet und zugeordnet.
extra_body	Weitergeleitet und mit der vom Framework bereitgestellten Agentreferenz zusammengeführt.
Samplingparameter, Metadaten, user, storeund response_format	Weitergeleitet, aber die Foundry-Agent- oder Modellkonfiguration kann diese außer Kraft setzen oder einschränken.

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.

Tip

Verwenden Sie Agent(client=FoundryChatClient(...)) diese Option, wenn Sie die Steuerung über Anweisungen, Generierungsoptionen oder Tools pro Ausführung benötigen.

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(

Tip

Ein vollständiges Beispiel finden Sie im using_deployed_agent.py Beispiel .

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.

Note

FoundryAgent Integration für Eingabeaufforderungs- und gehostete Agents ist derzeit nicht für Agent Framework Go verfügbar. Den neuesten Status finden Sie im Agent Framework Go-Repository .

Ausführen, Streamen und Fortsetzen von Unterhaltungen

Verwenden Sie nach dem Herstellen der Verbindung dieselben APIs wie andere Agent Framework-Agents:

• Führen Sie eine Anforderung mit RunAsync oder run.
• Stream-Updates mit RunStreamingAsync oder run(..., stream=True).
• Verwenden Sie eine Wiederverwendung, AgentSession um eine Unterhaltung fortzusetzen.
• Verwenden Sie findry serverseitige Unterhaltungs-APIs, wenn die Unterhaltung sichtbar und im Foundry-Projekt beibehalten werden muss.

Behalten Sie die Namen, Versionen, Endpunkte und Unterhaltungsbezeichner des Foundry-Agents im vertrauenswürdigen serverseitigen Zustand bei. Autorisieren Sie den Anrufer, bevor Sie eine vorhandene Unterhaltung fortsetzen.

Nächste Schritte

Überprüfen Microsoft Foundry-Modellanbieters