Microsoft Foundry 代理服務

FoundryAgent將 Agent Framework 連接到由 Microsoft Foundry Agent Service 管理的代理定義。代理程式的模型、指令、託管工具及版本皆在 Foundry 中設定;你的應用程式會連接到該定義，並使用標準的 Agent Framework 執行、串流和會話 API。

使用此整合功能：

提示代理，亦即在伺服器端定義、已命名並設有版本的代理。
託管代理，亦即已部署並可透過代理專屬端點存取的代理應用程式。

若想直接推論您的應用程式擁有代理定義的模型，請參閱 Microsoft Foundry 模型提供者。若要將代理框架應用程式部署為託管代理，請參見 Foundry 託管代理。

安裝套件

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

連接至提示代理程式

為 Foundry 專案建立AIProjectClient，並將AgentReference包裝為FoundryAgent。當應用程式必須使用特定的 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?"));

你也可以取回 a ProjectsAgentRecord 以使用其最新版本，或 a ProjectsAgentVersion 取用明確取得的版本，然後將該物件傳給 projectClient.AsAIAgent(...)。

取得最新的 Prompt Agent 版本

當應用程式應該依名稱解析最新註冊版本時，請使用 AgentAdministrationClient 。

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

這很重要

A FoundryAgent 使用其 Foundry 定義中儲存的模型、指令及託管工具。在 Foundry 中設定這些功能;客戶端無法在執行時替換它們。

Warning

DefaultAzureCredential 方便於開發。在生產環境中，建議優先使用特定憑證，例如 ManagedIdentityCredential，以避免非預期的憑證探測。

連接託管代理

託管代理會暴露一個代理專屬的 OpenAI 端點。從專案端點和註冊代理人名稱建立端點，然後交給 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();

端點管理員控制的版本選擇器決定活躍的託管代理版本。

安裝套件

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"

用 FOUNDRY_AGENT_VERSION 來作提示代理。託管代理程式可以省略它。

連線至提示代理程式

提供專案端點、代理名稱和代理版本。該服務提供儲存的模型、指令及託管工具配置。

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

如果 Prompt Agent 宣告了本地函式工具，建構tools=時將匹配的可呼叫函式傳遞過去FoundryAgent，讓客戶端在請求時能執行。請參閱 Prompt Agent 發佈與連結範例。

連線至託管代理程式

託管代理則不需要 agent_version。連結專案端點及註冊代理人名稱。

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

什麼方法有效，什麼無效 `FoundryAgent`

FoundryAgent 連接到 Foundry 中已存在的代理定義。儲存的指令和工具配置具有權威效力，因此客戶端的行為會不同於由應用程式擁有的 Agent(client=FoundryChatClient(...))。

Tools

傳遞給 `FoundryAgent(...)` 的工具類型	行為
`FunctionTool`並可呼叫本地的 Python	僅在 Foundry 代理上已有匹配函式定義時才支援。當 Foundry 請求時，該可呼叫物件會在應用程式流程中執行。
託管工具，包括網頁搜尋、程式碼直譯器、檔案搜尋、MCP、影像產生，以及 Microsoft Foundry 工具箱	請依 Foundry 代理定義配置這些。在用戶端傳遞它們，並不會將它們加入由服務管理的代理程式。

關於工具箱附件及直接 MCP 使用指引，請參見 Microsoft Foundry 工具箱。

你無法在施工時註冊新的模型可見工具。傳遞可呼叫函式只會提供 Foundry 代理已經宣告的函式的本地實作。

上下文提供者

情境提供者行為	適用於 `FoundryAgent`？
新增訊息，例如擷取的記憶、RAG 片段或使用者個人資料資訊	Yes. 注入的上下文會隨請求一同轉發。
持續或觀察對話	Yes. 提供者會在本機端於請求與回應前後執行。
動態新增工具	不行，除非這些工具已在 Foundry 代理程式定義中宣告。

當應用程式需要動態工具選擇、技能載入，或任何在執行時改變模型可見工具的行為時，會使用此 Agent(client=FoundryChatClient(...)) 方法。

執行選項

因為 Foundry 代理人定義才是權威來源，所以並非所有透過 default_options 或 agent.run(...) 傳入的選項都會被採用。

Option	提示代理程式行為
`model`	已忽略。此模型源自於 Foundry 代理程式定義。
`tools`、`tool_choice`、`parallel_tool_calls`	已從請求中移除。工具必須依 Foundry 代理定義宣告。
`instructions` 以及系統或開發者訊息	已忽略。已儲存的 Foundry 指示具有權威性。
`conversation_id`	在適用時，會被使用並映射到 Foundry agent session 中。
`extra_body`	已轉發並與框架提供的代理程式參考合併。
取樣參數、元資料、 `user`、 `store`、 `response_format`	會予以轉發，但 Foundry 代理程式或模型組態可以覆寫或限制這些設定。

託管代理會接受相同的用戶端過濾，但部署的代理可以接受、忽略或重新詮釋任何轉發的選項。將行為與特定託管代理（Hosted Agent）進行驗證。

Tip

當你需要每次執行都控制指令、產生選項或工具時使用 Agent(client=FoundryChatClient(...)) 。

管理託管代理服務會話

使用服務端工作階段的託管代理需要使用預覽版 Responses 介面：

當應用程式必須將服務會話綁定到租戶或使用者時，明確建立服務會話，然後將其識別碼包裝為代理框架會話。

    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

完整範例請參考範例using_deployed_agent.py。

設定自訂的 HTTP 逾時時間

FoundryAgent 預設會繼承 OpenAI SDK 的逾時設定。在多回合對話或網路狀況需要不同限制時，可在幾秒內傳入 timeout=。

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

逾時會套用於每個代理各自的 HTTP 用戶端副本，且不會影響共用相同 AIProjectClient 的其他代理。

備註

FoundryAgent Prompt 與 Hosted Agents 的整合目前無法在 Agent Framework Go 上提供。最新狀態請參閱 Agent Framework Go 倉庫。

跑步、直播並繼續對話

連線後，使用與其他代理框架代理相同的 API：

使用 RunAsync 或 run 執行請求。
使用 RunStreamingAsync 或 run(..., stream=True) 串流傳輸更新。
重複使用一個 AgentSession 以繼續對話。
當對話必須在 Foundry 專案中可見且持續存在時，請使用 Foundry 伺服器端對話 API。

保持 Foundry 代理的名稱、版本、端點及對話識別碼處於受信任的伺服器端狀態。在恢復任何現有對話前，先授權來電者。

下一步

檢閱 Microsoft Foundry 模型提供者

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-25

Microsoft Foundry 代理服務

安裝套件

連接至提示代理程式

取得最新的 Prompt Agent 版本

連接託管代理

安裝套件

Configuration

連線至提示代理程式

連線至託管代理程式

什麼方法有效，什麼無效 FoundryAgent

Tools

上下文提供者

執行選項

管理託管代理服務會話

設定自訂的 HTTP 逾時時間

跑步、直播並繼續對話

下一步

意見反應

其他資源

什麼方法有效，什麼無效 `FoundryAgent`