Microsoft Foundry Agent Service

FoundryAgentansluter Agent Framework till en agentdefinition som hanteras av Microsoft Foundry Agent Service. Agentens modell, instruktioner, värdbaserade verktyg och version konfigureras i Foundry. ditt program ansluter till den definitionen och använder standard-API:er för Agent Framework-körning, strömning och session.

Använd den här integreringen för:

Fråga agenter, som heter och versionshanterade agentdefinitioner på serversidan.
Värdbaserade agenter, som distribueras agentprogram som nås via en agentspecifik slutpunkt.

Information om direkt modellinferens där ditt program äger agentdefinitionen finns i Microsoft Foundry-modellprovider. Information om hur du distribuerar ett Agent Framework-program som värdbaserad agent finns i Foundry Hosted Agents (Foundry Hosted Agents).

Installera programvarupaketen

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

Ansluta till en promptagent

Skapa ett AIProjectClient för Foundry-projektet och omslut som AgentReference en 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 programmet ska matcha den senaste registrerade versionen med namn.

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 använder modellen, instruktionerna och värdbaserade verktyg som lagras i dess Foundry-definition. Konfigurera dessa funktioner i Foundry; klienten kan inte ersätta dem vid körning.

Varning

DefaultAzureCredential är praktiskt för utveckling. I produktion föredrar du en specifik autentiseringsuppgift, till exempel ManagedIdentityCredential för att undvika oavsiktlig avsökning av autentiseringsuppgifter.

Ansluta till en värdbaserad agent

Värdbaserade agenter exponerar 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ärdbaserade agenter kan utelämna det.

Ansluta till en promptagent

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 promptagent deklarerar ett lokalt funktionsverktyg skickar du det matchande anropsbara objektet när tools= du skapar så att FoundryAgent klienten kan köra det när det begärs. Se exemplet för att publicera och ansluta till promptagenten.

Ansluta till en värdbaserad agent

Värdbaserade agenter kräver agent_versioninte . 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

Verktygstyp skickad till `FoundryAgent(...)`	Behavior
`FunctionTool`med en lokal Python anropsbar	Stöds endast när matchande funktionsdefinition redan finns på Foundry-agenten. Anropsbara körs i programprocessen när Foundry begär det.
Värdbaserade verktyg, inklusive webbsökning, kodtolkare, filsökning, MCP, bildgenerering och Microsoft Foundry Toolbox	Konfigurera dessa i foundry-agentdefinitionen. Att skicka dem på klientsidan lägger inte till dem i den tjänsthanterade agenten.

Vägledning för verktygslådans bifogade filer och direkt MCP-förbrukning finns i Microsoft Foundry Toolbox.

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

Kontextleverantörer

Beteende för kontextprovider	Fungerar med `FoundryAgent`?
Lägger till meddelanden, till exempel hämtat minne, RAG-kodfragment eller användarprofilinformation	Yes. Den inmatade kontexten vidarebefordras med begäran.
Bevarar eller observerar konversationen	Yes. Providern körs lokalt runt begäran och svaret.
Lägger till verktyg dynamiskt	Nej, såvida inte dessa verktyg redan har deklarerats i foundry-agentdefinitionen.

Använd Agent(client=FoundryChatClient(...)) när programmet behöver dynamiskt verktygsval, kompetensinläsning eller något beteende som ändrar modell synliga verktyg 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.

Option	Fråga agentens beteende
`model`	Ignoreras. Modellen kommer från foundry-agentdefinitionen.
`tools`, , `tool_choiceparallel_tool_calls`	Har tagits bort från begäran. Verktyg måste deklareras i foundry-agentdefinitionen.
`instructions` och system- eller utvecklarmeddelanden	Ignoreras. De lagrade Foundry-instruktionerna är auktoritativa.
`conversation_id`	Används och mappas till Foundry-agentsessionen när det är tillämpligt.
`extra_body`	Vidarebefordras och sammanfogas med referensen för den ramverksbaserade agenten.
Samplingsparametrar, metadata, `user`, `store`och `response_format`	Vidarebefordras, men Foundry-agenten eller modellkonfigurationen kan åsidosätta eller begränsa dem.

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.

Tips/Råd

Använd Agent(client=FoundryChatClient(...)) när du behöver kontroll per körning över instruktioner, generationsalternativ eller verktyg.

Hantera en värdbaserad agenttjänstsession

Värdbaserade agenter som använder sessioner på tjänstsidan kräver förhandsversionen av svarsytan:

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(

Tips/Råd

Se exempletusing_deployed_agent.py för ett fullständigt exempel.

Ange en anpassad HTTP-timeout

FoundryAgent ärver OpenAI SDK-tidsgränsen som standard. Skicka timeout= in sekunder när konversationer eller nätverksförhållanden i flera svängar 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.

Anmärkning

FoundryAgent integrering för prompt- och värdbaserade agenter är för närvarande inte tillgänglig för Agent Framework Go. Se Agent Framework Go-lagringsplatsen för den senaste statusen.

Köra, strömma och fortsätt konversationer

När du har anslutit använder du samma API:er som andra Agent Framework-agenter:

Kör en begäran med RunAsync eller run.
Stream-uppdateringar med RunStreamingAsync eller run(..., stream=True).
Återanvänd en AgentSession för att fortsätta en konversation.
Använd Konversations-API:er på Foundry-serversidan när konversationen måste vara synlig och bevarad i Foundry-projektet.

Behåll Foundry-agentnamn, versioner, slutpunkter och konversationsidentifierare i betrott tillstånd på serversidan. Auktorisera anroparen innan du återupptar en befintlig konversation.

Nästa steg

Granska Microsoft Foundry-modellprovider

Feedback

Var den här sidan till hjälp?

Last updated on 2026-08-13

Microsoft Foundry Agent Service

Installera programvarupaketen

Ansluta till en promptagent

Hämta den senaste promptagentversionen

Ansluta till en värdbaserad agent

Installera programvarupaketen

Configuration

Ansluta till en promptagent

Ansluta till en värdbaserad agent

Vad fungerar och vad som inte fungerar med FoundryAgent

Tools

Kontextleverantörer

Körningsalternativ

Hantera en värdbaserad agenttjänstsession

Ange en anpassad HTTP-timeout

Köra, strömma och fortsätt konversationer

Nästa steg

Feedback

Ytterligare resurser

Vad fungerar och vad som inte fungerar med `FoundryAgent`