FoundryAgent将代理框架连接到由 Microsoft Foundry 代理服务管理的代理定义。 代理的模型、说明、托管工具和版本在 Foundry 中配置;应用程序连接到该定义并使用标准代理框架运行、流式处理和会话 API。
将此集成用于：
- 提示代理，这些代理已命名和版本控制服务器端代理定义。
- 托管代理，这是通过特定于代理的终结点访问的已部署代理应用程序。
有关应用程序拥有代理定义的直接模型推理，请参阅 Microsoft Foundry 模型提供程序。 若要将 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?"));
还可以检索 a ProjectsAgentRecord 以使用其最新版本或使用 ProjectsAgentVersion 显式检索的版本，然后将该对象 projectClient.AsAIAgent(...)传递给 。
检索最新的提示代理版本
当应用程序应按名称解析最新注册的版本时使用 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?"));
Important
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"
为“Prompt Agents”使用 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(...)) 。
管理托管代理服务会话
使用服务端会话的托管代理需要预览响应图面：
当应用程序必须将其绑定到租户或用户时，显式创建服务会话，然后将其标识符包装为代理框架会话。
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 代理名称、版本、终结点和会话标识符保持受信任的服务器端状态。 在恢复任何现有对话之前授权呼叫方。