Microsoft Foundry Agent Service

Installera programvarupaketen

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

Anslut till Prompt Agent

Skapa ett AIProjectClient för Foundry-projektet och omslut ett AgentReference som ett FoundryAgent. Fäst versionen när programmet måste använda en specifik promptagentdefinition.

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

Du kan också hämta en ProjectsAgentRecord för att använda den senaste versionen eller en ProjectsAgentVersion för att använda en explicit hämtad version och sedan skicka objektet till projectClient.AsAIAgent(...).

Hämta den senaste promptagentversionen

Använd AgentAdministrationClient när applikationen ska lösa upp den senast registrerade versionen utifrån namnet.

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

Ansluta till en värdbaserad agent

Hanterade agenter tillhandahåller en agentspecifik OpenAI-slutpunkt. Skapa slutpunkten från projektslutpunkten och det registrerade agentnamnet och skicka den sedan till 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();

Slutpunktens administratörsstyrda versionsväljare avgör den aktiva värdbaserade agentversionen.

Installera programvarupaketen

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"

Använd FOUNDRY_AGENT_VERSION för promptagenter. Värdagenter kan utelämna det.

Anslut till en prompt-agent

Ange projektslutpunkt, agentnamn och agentversion. Tjänsten tillhandahåller den lagrade modellen, instruktionerna och konfigurationen av värdbaserade verktyg.

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()

Om en Prompt Agent deklarerar ett lokalt funktionsverktyg, skickar du det motsvarande anropsbara objektet via tools= när du skapar FoundryAgent, så att klienten kan köra det när det begärs. Se exemplet för publicering och anslutning av Prompt Agent.

Ansluta till en värdbaserad agent

Hostade agenter kräver inte agent_version. Anslut med projektslutpunkten och det registrerade agentnamnet.

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}")

Vad fungerar och vad som inte fungerar med FoundryAgent

FoundryAgent ansluter till en agentdefinition som redan finns i Foundry. De lagrade instruktionerna och verktygskonfigurationen är auktoritativa, så beteendet på klientsidan skiljer sig från ett programägt Agent(client=FoundryChatClient(...)).

Tools

Vägledning om anslutning till Toolbox och direkt användning av MCP finns i Microsoft Foundry Toolbox.

Du kan inte registrera ett nytt verktyg som är synligt för modellen vid konstruktion. Att skicka en funktion som kan anropas tillhandahåller endast den lokala implementeringen för en funktion som Foundry-agenten redan deklarerar.

Kontextleverantörer

Använd Agent(client=FoundryChatClient(...)) när applikationen behöver dynamiskt val av verktyg, inläsning av färdigheter eller något beteende som ändrar vilka verktyg som är synliga för modellen vid körning.

Körningsalternativ

Eftersom Foundry-agentdefinitionen är källan till sanningen, är inte alla alternativ som skickas igenom default_options eller agent.run(...) respekteras.

Värdbaserade agenter får samma filtrering på klientsidan, men den distribuerade agenten kan acceptera, ignorera eller omtolka alla vidarebefordrade alternativ. Kontrollera beteendet mot den specifika värdbaserade agenten.

Hantera en värdbaserad agenttjänstsession

Hostade agenter som använder sessioner på serversidan kräver förhandsversionen av Responses-ytan:

Skapa tjänstsessionen explicit när programmet måste binda den till en klientorganisation eller användare och omslut sedan dess identifierare som en Agent Framework-session.

    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(

Ange en anpassad HTTP-timeout

FoundryAgent ärver OpenAI SDK-tidsgränsen som standard. Ange timeout= i sekunder när konversationer i flera omgångar eller nätverksförhållanden kräver en annan gräns.

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,
)

Tidsgränsen tillämpas på en kopia per agent av HTTP-klienten och påverkar inte andra agenter som delar samma AIProjectClient.