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 výzvy, kteří mají názvy a definice agenta na straně serveru s verzí
Hostovaní agenti, které jsou nasazené aplikace agentů, dosáhly prostřednictvím koncového bodu specifického pro agenta.

Přímé odvozování modelu, kde vaše aplikace vlastní definici agenta, najdete v tématu Microsoft zprostředkovatele modelu Foundry. Pokud chcete nasadit aplikaci Agent Framework jako hostovaného agenta, přečtěte si téma Foundry Hostovaní agenti.

Instalace balíčků

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

Připojení k agentu výzvy

Vytvořte pro AIProjectClient projekt Foundry a zabalte ho AgentReference jako .FoundryAgent Připněte verzi, když aplikace musí použít konkrétní definici agenta výzvy.

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 , aby používal jeho nejnovější verzi nebo ProjectsAgentVersion použít explicitně načtenou verzi a pak předat tento objekt projectClient.AsAIAgent(...).

Načtení nejnovější verze agenta výzvy

Použijte AgentAdministrationClient , když by aplikace měla přeložit nejnovější zaregistrovanou verzi podle 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?"));

Important

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 koncový bod z koncového bodu projektu a název registrovaného agenta a pak ho AIProjectClient.AsAIAgent(...)předejte .

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řipojení k agentu výzvy

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 agent výzvy deklaruje nástroj místní funkce, předejte při vytváření FoundryAgent odpovídající volánítools=, aby ho klient mohl spustit při vyžádání. Podívejte se na ukázku publikování a připojení agenta výzvy.

Připojení k hostovanému agentu

Hostovaní agenti nevyžadují agent_version. Připojte se ke koncovému 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é instrukce a konfigurace nástroje jsou autoritativní, takže chování na straně klienta se liší od aplikace vlastněné Agent(client=FoundryChatClient(...))aplikací .

Tools

Typ nástroje předaný do `FoundryAgent(...)`	Chování
`FunctionTool`s místním Python volatelným	Podporováno pouze v případech, kdy v agentu Foundry již existuje definice odpovídající funkce. Volající se spustí v procesu aplikace, když ho Foundry požá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. Předání na straně klienta je nepřidá do agenta spravovaného službou.

Pokyny k použití sady nástrojů a přímé spotřeby MCP najdete v tématu Microsoft Sada nástrojů Foundry.

Nový model viditelný nástroj není možné zaregistrovat v době výstavby. 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.
Zachovají nebo sledují konverzaci.	Yes. Zprostředkovatel běží místně kolem 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í

Vzhledem k tomu, že definice agenta Foundry je zdrojem pravdy, ne každá možnost prošla default_options nebo agent.run(...) je dodržena.

Option	Zobrazení výzvy k chování agenta
`model`	Ignorovaný. Model pochází z definice agenta Foundry.
`tools`, , `tool_choiceparallel_tool_calls`	Odebráno z požadavku. Nástroje musí být deklarovány v definici agenta Foundry.
`instructions` zpráv o systému nebo vývojáři	Ignorovaný. Uložené pokyny foundry jsou autoritativní.
`conversation_id`	Používá se a mapuje na relaci agenta Foundry, pokud je to možné.
`extra_body`	Přeposlané a sloučené s referenčními informacemi o agentech poskytovaných architekturou.
Parametry vzorkování, metadata, `user`, `store`a `response_format`	Přeposlaný, ale konfigurace agenta Foundry nebo modelu může přepsat 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í pro konkrétního hostovaného agenta.

Tip

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

Správa relace hostované služby agenta

Hostovaní agenti, kteří používají relace na straně služby, vyžadují plochu odpovědí na 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. Předání timeout= v sekundách, když vícenásobné konverzace nebo síťové podmínky 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.

Note

FoundryAgent integrace pro výzvy a hostované agenty není v současné době dostupná 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).
AgentSession Znovu použijte možnost pokračovat v konverzaci.
Rozhraní API konverzace na straně serveru Foundry použijte, když musí být konverzace viditelná a trvalá 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-13

Služba agenta Microsoft Foundry

Instalace balíčků

Připojení k agentu výzvy

Načtení nejnovější verze agenta výzvy

Připojení k hostovanému agentu

Instalace balíčků

Configuration

Připojení k agentu výzvy

Připojení k hostovanému agentu

Co funguje a co nefunguje s FoundryAgent

Tools

Zprostředkovatelé kontextu

Možnosti spuštění

Správa relace hostované služby agenta

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`