Služba agenta Microsoft Foundry

FoundryAgentpřipojí rozhraní Agent Framework k definici agenta spravované službou Microsoft Foundry Agent Service. Model agenta, pokyny, hostované nástroje a verze jsou nakonfigurovány v Foundry; vaše aplikace se připojí k této definici a používá standardní rozhraní API pro spouštění, streamování a relace.

Tuto integraci použijte pro:

Agenti promptů, což jsou pojmenované a verzované definice agentů na straně serveru.
Hostovaní agenti, což jsou nasazené aplikace agentů přístupné prostřednictvím koncového bodu specifického pro daného agenta.

Informace o přímé inferenci modelu, kde vaše aplikace má vlastní definici agenta, najdete v tématu zprostředkovatel modelu Microsoft Foundry. Pokud chcete nasadit aplikaci Agent Framework jako hostovaného agenta, viz Hostovaní agenti ve Foundry.

Instalace balíčků

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

Připojte se k agentovi Prompt

Vytvořte AIProjectClient pro projekt Foundry a zabalte AgentReference jako FoundryAgent Připnout verzi, pokud aplikace musí používat specifickou definici Prompt Agent.

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

Můžete také načíst ProjectsAgentRecord, abyste použili jeho nejnovější verzi, nebo ProjectsAgentVersion, abyste použili explicitně načtenou verzi, a potom tento objekt předat do projectClient.AsAIAgent(...).

Načtěte nejnovější verzi agenta Prompt Agent

Použijte AgentAdministrationClient, když má aplikace vyhledat nejnovější zaregistrovanou verzi na základě názvu.

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

Důležité

A FoundryAgent používá model, pokyny a hostované nástroje uložené v definici Foundry. Konfigurace těchto funkcí v Foundry; klient je nemůže za běhu nahradit.

Warning

DefaultAzureCredential je vhodný pro vývoj. V produkčním prostředí dáváte přednost konkrétním přihlašovacím údajům, například ManagedIdentityCredential abyste se vyhnuli neúmyslnému testování přihlašovacích údajů.

Připojení k hostovanému agentu

Hostovaní agenti zpřístupňují koncový bod OpenAI specifický pro agenta. Sestavte endpoint z endpointu projektu a názvu registrovaného agenta a poté jej předejte do 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();

Selektor verzí řízený správcem koncového bodu určuje aktivní verzi hostovaného agenta.

Instalace balíčků

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"

Použijte FOUNDRY_AGENT_VERSION pro Prompt agenty. Hostovaní agenti ho můžou vynechat.

Připojte se k Prompt Agent

Zadejte koncový bod projektu, název agenta a verzi agenta. Služba poskytuje uložený model, pokyny a konfiguraci hostovaného nástroje.

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

Pokud Prompt Agent deklaruje nástroj lokální funkce, předejte odpovídající volatelný objekt prostřednictvím tools= při vytváření FoundryAgent, aby jej klient mohl na požádání spustit. Podívejte se na ukázku publikování a připojení nástroje Prompt Agent.

Připojení k hostovanému agentu

Hostovaní agenti nevyžadují agent_version. Připojte se pomocí koncového bodu projektu a názvu registrovaného agenta.

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

Co funguje a co nefunguje s `FoundryAgent`

FoundryAgent připojí se k definici agenta, která už v Foundry existuje. Uložené pokyny a konfigurace nástroje jsou směrodatné, proto se chování na straně klienta liší od Agent(client=FoundryChatClient(...)), který je vlastněn aplikací.

Tools

Typ nástroje předaný do `FoundryAgent(...)`	Behavior
`FunctionTool` s místním volatelným objektem Python	Podporováno pouze v případech, kdy v agentu Foundry již existuje definice odpovídající funkce. Volatelná funkce běží v procesu aplikace, když ji Foundry vyžádá.
Hostované nástroje, včetně vyhledávání na webu, interpretu kódu, vyhledávání souborů, MCP, generování obrázků a sady nástrojů Microsoft Foundry	Nakonfigurujte je v definici agenta Foundry. Jejich předání na straně klienta je nepřidá do agenta spravovaného službou.

Pokyny k připojení Toolboxu a pro přímé využití MCP najdete v tématu Microsoft Foundry Toolbox.

Při konstrukci nelze zaregistrovat nový nástroj viditelný pro model. Předání funkce, kterou lze volat, poskytuje pouze místní implementaci funkce, kterou již agent Foundry deklaruje.

Zprostředkovatelé kontextu

Chování zprostředkovatele kontextu	Funguje s `FoundryAgent`?
Přidá zprávy, jako jsou načtená paměť, fragmenty rag nebo informace o profilu uživatele.	Yes. Injektovaný kontext je předán s požadavkem.
Uchovává nebo sleduje konverzaci.	Yes. Poskytovatel je spouštěn lokálně při zpracování požadavku a odpovědi.
Dynamické přidání nástrojů	Ne, pokud tyto nástroje již nejsou deklarovány v definici agenta Foundry.

Použijte Agent(client=FoundryChatClient(...)) , když aplikace potřebuje dynamický výběr nástrojů, načítání dovedností nebo jakékoli chování, které mění nástroje viditelné modelem za běhu.

Možnosti spuštění

Protože definice agenta Foundry je rozhodujícím zdrojem, ne každá možnost předaná prostřednictvím default_options nebo agent.run(...) se zohlední.

Option	Vyžádat chování agenta
`model`	Ignorovaný. Model pochází z definice agenta Foundry.
`tools`, `tool_choice`, `parallel_tool_calls`	Odstraněno z požadavku. Nástroje musí být deklarovány v definici agenta Foundry.
`instructions` a systémové nebo vývojářské zprávy	Ignorovaný. Uložené pokyny Foundry jsou směrodatné.
`conversation_id`	Používá se a mapuje na relaci agenta Foundry, pokud je to možné.
`extra_body`	Přeposláno a sloučeno s referencí na agenta poskytovanou frameworkem.
Parametry vzorkování, metadata, `user`, `store`a `response_format`	Jsou předány dál, ale konfigurace agenta Foundry nebo modelu je může přebít nebo omezit.

Hostovaní agenti obdrží stejné filtrování na straně klienta, ale nasazený agent může přijmout, ignorovat nebo znovu interpretovat jakoukoli přeposílanou možnost. Ověřte chování vůči konkrétnímu hostovanému agentovi.

Tip

Použijte Agent(client=FoundryChatClient(...)) , když potřebujete kontrolu nad pokyny, možnostmi generování nebo nástroji pro jednotlivé spuštění.

Spravovat relaci služby Hostovaný agent

Hostovaní agenti, kteří používají relace na straně služby, vyžadují rozhraní Responses ve verzi Preview:

Relaci služby vytvořte explicitně, když ji aplikace musí svázat s tenantem nebo uživatelem, a pak jeho identifikátor zabalte jako relaci rozhraní Agent Framework.

    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

Kompletní příklad najdete v ukázceusing_deployed_agent.py.

Nastavení vlastního časového limitu HTTP

FoundryAgent ve výchozím nastavení dědí časový limit sady OpenAI SDK. Zadejte timeout= v sekundách, pokud vícekolové konverzace nebo podmínky sítě vyžadují jiný limit.

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

Časový limit se použije u kopie klienta HTTP pro jednotlivé agenty a nemá vliv na ostatní agenty, kteří sdílejí stejné AIProjectClient.

Poznámka:

FoundryAgent integrace pro agenty Prompt a Hosted není momentálně k dispozici pro Agent Framework Go. Nejnovější stav najdete v úložišti Agent Framework Go .

Spouštění, streamování a pokračování konverzací

Po připojení použijte stejná rozhraní API jako ostatní agenti rozhraní Agent Framework:

Spusťte žádost s RunAsync nebo run.
Streamování aktualizací pomocí RunStreamingAsync nebo run(..., stream=True).
Znovu použijte AgentSession k pokračování v konverzaci.
Použijte serverová rozhraní API pro konverzace ve Foundry, když konverzace musí být viditelná a uložená v projektu Foundry.

Uchovávejte názvy agentů Foundry, verze, koncové body a identifikátory konverzací v důvěryhodném stavu na straně serveru. Před obnovením jakékoli existující konverzace autorizujete volajícího.

Další kroky

Kontrola poskytovatele modelu Microsoft Foundry

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-08-25

Služba agenta Microsoft Foundry

Instalace balíčků

Připojte se k agentovi Prompt

Načtěte nejnovější verzi agenta Prompt Agent

Připojení k hostovanému agentu

Instalace balíčků

Configuration

Připojte se k Prompt Agent

Připojení k hostovanému agentu

Co funguje a co nefunguje s FoundryAgent

Tools

Zprostředkovatelé kontextu

Možnosti spuštění

Spravovat relaci služby Hostovaný agent

Nastavení vlastního časového limitu HTTP

Spouštění, streamování a pokračování konverzací

Další kroky

Váš názor

Další materiály

Co funguje a co nefunguje s `FoundryAgent`