技术速递|使用 Microsoft Agent Framework for Go 预配置智能体
Microsoft Agent Framework for Go 可以帮助你构建智能体,使其能够跟踪任务、保存和查阅笔记、加载可复用的技能,以及调用应用程序提供的工具。通过审批规则,应用程序可以处理需要用户作出决定的工具调用。追踪功能则会提供调用模型和工具时的耗时及错误数据,方便进行问题排查。
要将这些能力组合起来,需要配置上下文提供程序、中间件、历史记录和会话状态。如果希望多个智能体使用相同的默认设置,那么每次都重复进行这些配置就会变得十分繁琐。
为了解决重复配置的问题,我们引入了智能体运行框架,可通过 agent/harness 包使用。智能体运行框架是应用程序代码的一部分,负责协调工具执行,并在模型调用之间提供上下文。
该软件包从 Microsoft Agent Framework for Go v0.2.0 版本开始提供。目前,该框架仍处于公共预览阶段。
运行框架配置了哪些内容
harness.AgentConfig 会返回一个添加了运行框架默认配置的 agent.Config。这个辅助函数会将你提供的工具与内置工具组合起来,并包含你指定的中间件和上下文提供程序。使用该配置配合相应的提供程序构造函数,即可创建智能体。
智能体的 CreateSession 方法会创建一个保存对话状态的 agent.Session 对象。后续调用 RunText 时,可以通过 agent.WithSession 传入同一个会话,以继续之前的对话。
默认配置包括:
-
默认指令: 运行框架会提供 Agent Framework 的
harness.DefaultInstructions文本,告诉模型将复杂任务拆分为多个步骤,使用工具验证结果,并在工具调用之间报告进度。 -
待办事项工具: 这些工具可以读取和更新会话中的结构化任务列表,让后续请求能够了解哪些工作尚未完成。
-
规划和执行模式: 智能体默认以规划模式启动,并根据当前模式使用相应指令,讨论计划或执行计划。需要注意的是,这些模式不会禁止工具使用,也不会提供任何沙盒隔离,仅用于指导智能体的行为方式。
-
FileMemory: 智能体可以在磁盘上保存和更新计划或调查结果,并在后续请求中通过文件名检索这些内容。
-
对话历史记录: 默认情况下,历史记录提供程序会将消息保存在内存中,并在每次模型调用后保存消息,包括中间工具调用及其结果。智能体可以在回答后续请求时使用这些工具结果。
-
技能: 基于文件的技能会将任务指令和 YAML 元数据保存在
SKILL.md文件中,同时可以包含参考文档、模板等可选的辅助文件。智能体可以根据需要加载相关指令和文件,而不必在初始提示词中包含所有操作流程。默认情况下,技能发现会在工作目录中查找,并排除agent-file-memory目录。技能也可以包含脚本,例如 Python 文件,但只有在应用程序提供脚本运行器时,这些脚本才会执行。 -
工具审批: 中间件会记住当前会话中已生效的长期审批,并应用你配置的自动审批规则,避免对符合规则的调用反复请求确认。对于仍然需要审批的调用,应用程序会收到一条请求,可以将其展示给用户,并通过同一个会话返回审批结果。
-
托管式网页搜索: 模型可以向服务请求网页搜索结果,因此应用程序无需自行构建搜索客户端。具体支持情况取决于所选的 API 和部署方式。如果不支持或不需要网页搜索,可以使用
DisableWebSearch将该工具排除在配置之外。 -
消息注入: 在运行过程中,应用程序可以向会话队列中添加额外输入,例如修改后的需求。注入器会在模型调用之间提供这些排队消息。通过这种方式,应用程序无需丢弃当前模型调用正在完成的工作。如果需要取消当前任务,则可以使用
context.WithCancel创建 Go context。 -
追踪: OpenTelemetry 会分别记录智能体运行、受支持的模型调用和本地工具调用。每条记录都包含执行耗时和错误信息。模型调用记录还会包含由提供程序报告的 Token 使用量。
运行框架指南介绍了 harness.Config 的配置项及其默认值。
使用 Foundry 运行智能体
下面的示例将针对一个 Go net/http 服务的规划助手运行两次请求。第一次请求要求智能体规划一个健康检查端点,将工作记录为待办事项,并将计划保存到 healthcheck.md 文件中。第二次请求要求智能体读取已保存的计划,并从同一个会话中列出尚未完成的任务。该示例需要 Go 1.26 或更高版本:
go mod init example.com/harness
go get github.com/microsoft/agent-framework-go@v0.2.0
使用一个支持 Responses API 和函数调用的模型部署所对应的 Foundry 项目。将 FOUNDRY_PROJECT_ENDPOINT 设置为项目终结点,例如 https://<resource-name>.``services.ai.azure.com/api/projects/<project-name>。将 FOUNDRY_MODEL 设置为模型部署名称。
在本地开发时,使用具有调用该模型部署权限的身份,通过 az login 登录。Foundry User 角色会授予所需的项目数据访问权限。该示例使用 DefaultAzureCredential,可以通过 Azure CLI 凭据进行身份验证。程序会向 Foundry 发送模型请求,并产生相应的使用费用。
将以下内容保存为 main.go:
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/agent/harness"
"github.com/microsoft/agent-framework-go/provider/foundryprovider"
)
func main() {
endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
deployment := os.Getenv("FOUNDRY_MODEL")
if endpoint == "" || deployment == "" {
log.Fatal("FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL are required")
}
credential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("create credential: %v", err)
}
cfg, err := harness.AgentConfig(
// This example doesn't need hosted web search
harness.Config{DisableWebSearch: true},
agent.Config{Name: "ProjectAssistant"},
)
if err != nil {
log.Fatalf("configure harness: %v", err)
}
a := foundryprovider.NewAgent(
endpoint,
credential,
foundryprovider.ModelDeployment(deployment),
foundryprovider.AgentConfig{
Config: cfg,
Instructions: "Help with software engineering tasks. Use memory and to-do items when asked.",
// Retain conversation history in agent.Session rather than at the service.
DisableStoreOutput: true,
},
)
ctx := context.Background()
session, err := a.CreateSession(ctx)
if err != nil {
log.Fatalf("create session: %v", err)
}
for _, prompt := range []string{
"Plan a health-check endpoint for a Go net/http service. Record the tasks as to-do items and save the plan in healthcheck.md.",
"Read healthcheck.md and list the remaining to-do items. Explain what you would implement first, without editing the service.",
} {
fmt.Printf("User: %s\n", prompt)
response, err := a.RunText(ctx, prompt, agent.WithSession(session)).Collect()
if err != nil {
log.Fatalf("run agent: %v", err)
}
fmt.Printf("Assistant: %s\n\n", response)
}
}
运行程序:
go mod tidy
go run .
程序会依次输出每条提示词及智能体的响应。智能体会利用第一次请求中创建的任务列表和保存的计划来回答第二次请求。具体的工具选择和响应措辞会因模型而异。
该示例在 foundryprovider.AgentConfig 中将 DisableStoreOutput 设置为 true,以禁用 Foundry 的响应存储功能。在这里,运行框架的历史记录提供程序会将对话保存在本地 agent.Session 中,因此程序不依赖 Foundry 重放已存储的响应。如果你希望稍后检索响应,或使用由 Foundry 管理的对话历史记录,则服务端存储功能会很有用。
状态存储在哪里
session 变量指向 Go 进程内存中的一个 agent.Session 对象。该会话保存待办事项和记忆文件夹路径,而 FileMemory 则会将计划写入程序工作目录下的 agent-file-memory/<session-folder>/healthcheck.md 文件。
再次运行程序时,会创建一个新的会话和不同的文件夹。
如果希望应用程序在重启后能够继续执行任务,就需要保存并恢复会话状态,同时使用相同的记忆根目录。记忆与持久化指南介绍了如何使用 encoding/json 序列化会话。恢复会话后,系统会还原任务列表,并自动选择之前使用的记忆文件夹。
如果你的智能体需要利用的文档上下文超出了提示词所能容纳的范围,可以参考我们的嵌入与向量搜索文章,了解如何根据语义检索相关文本片段。
更多推荐



所有评论(0)