Microsoft Foundry 代理服务

FoundryAgent将代理框架连接到由 Microsoft Foundry 代理服务管理的代理定义。代理的模型、说明、托管工具和版本在 Foundry 中配置;应用程序连接到该定义并使用标准代理框架运行、流式处理和会话 API。

将此集成用于：

提示代理，即在服务器端定义的、已命名并进行版本管理的代理。
托管代理，即通过代理专用端点访问的已部署代理应用程序。

有关由应用程序自行定义代理的直接模型推理，请参阅 Microsoft Foundry model provider。若要将 Agent Framework 应用程序部署为托管代理，请参阅 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。如果应用程序必须使用特定的提示代理定义，请锁定其版本。

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

还可以检索ProjectsAgentRecord以使用其最新版本，或者检索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?"));

重要

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

端点上由管理员控制的版本选择器决定当前使用的 Hosted Agent 版本。

安装软件包

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"

对 Prompt 智能体使用 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 声明了本地函数工具，请在构造 FoundryAgent 时通过 tools= 传递匹配的可调用对象，以便客户端在请求时能够执行它。请参阅提示代理发布和连接示例。

连接到托管代理

托管代理不需要 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(...)` 的工具类型	Behavior
将`FunctionTool`与本地 Python 可调用对象结合使用	仅当 Foundry 代理上已存在匹配函数定义时才受支持。当 Foundry 请求该可调用对象时，它会在应用程序进程中运行。
托管工具，包括 Web 搜索、代码解释器、文件搜索、MCP、图像生成和Microsoft Foundry 工具箱	在 Foundry 代理定义中配置这些配置。在客户端传递这些内容不会将其添加到由服务管理的代理。

有关附加工具箱和直接使用 MCP 的指南，请参阅Microsoft Foundry 工具箱。

无法在构造时注册新的模型可见工具。传入一个可调用的函数，只会为 Foundry 代理已声明的该函数提供本地实现。

上下文提供程序

上下文提供程序行为	可与 `FoundryAgent` 配合使用？
添加消息，例如检索的内存、RAG 代码段或用户配置文件信息	Yes. 注入的上下文随请求一起转发。
持久化或观察对话	Yes. 提供程序在本地围绕请求和响应运行。
动态添加工具	否，除非已在 Foundry 代理定义上声明这些工具。

当应用程序需要动态工具选择、技能加载或运行时更改模型可见工具的任何行为时使用 Agent(client=FoundryChatClient(...)) 。

运行选项

由于 Foundry 代理定义是权威来源，因此通过default_options或agent.run(...)传递的选项不一定都会生效。

选项	提示代理行为
`model`	已忽略。该模型源自 Foundry 代理的定义。
`tools`、`tool_choice`、`parallel_tool_calls`	从请求中删除。必须在 Foundry 代理定义中声明工具。
`instructions`以及系统消息或开发者消息	已忽略。存储的 Foundry 指令是权威的。
`conversation_id`	在适用时，将使用并映射到 Foundry 代理会话中。
`extra_body`	转发并与框架提供的代理引用合并。
采样参数、元数据、`user`和 `storeresponse_format`	这些内容会被转发，但 Foundry 代理或模型配置可以覆盖或限制它们。

托管代理接收相同的客户端筛选，但部署的代理可以接受、忽略或重新解释任何转发选项。针对特定的托管代理验证行为。

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 和托管代理的集成功能当前在 Agent Framework Go 中不可用。有关最新状态，请参阅 Agent Framework Go 存储库。

运行、流式传输和继续对话

连接后，使用与其他代理框架代理相同的 API：

使用 RunAsync 或 run. 运行请求。
使用 RunStreamingAsync 或 run(..., stream=True) 流式传输更新。
重新使用 AgentSession 以继续对话。
当会话必须可见并保留在 Foundry 项目中时，请使用 Foundry 服务器端会话 API。

使 Foundry 代理名称、版本、终结点和会话标识符保持受信任的服务器端状态。在恢复任何现有对话之前授权呼叫方。

后续步骤

查看 Microsoft Foundry 模型提供程序

反馈

此页面是否有帮助？

Last updated on 2026-09-01

Microsoft Foundry 代理服务

安装软件包

连接到提示代理

获取最新的 Prompt Agent 版本

连接到托管代理

安装软件包

Configuration

连接到提示代理

连接到托管代理

FoundryAgent 中哪些可行哪些不可行

Tools

上下文提供程序

运行选项

管理托管代理服务会话

设置自定义 HTTP 超时

运行、流式传输和继续对话

后续步骤

反馈

其他资源

`FoundryAgent` 中哪些可行哪些不可行