Microsoft Agent Framework for Go 详细部署与实践教程

Microsoft Agent Framework (MAF) for Go 是微软推出的、用于构建生产级 AI 代理（Agent）和多代理工作流的 Go 语言框架。它支持 Microsoft Foundry、Azure OpenAI、OpenAI 等模型提供商，并集成了 Model Context Protocol (MCP)、Agent2Agent (A2A) 等关键协议。

本教程将带你从环境配置到创建第一个工作流，完成在 Go 语言下的完整部署与开发实践。

第一步：环境准备与安装

1. 系统要求

  • Go 版本：需要 Go 1.21 或更高版本。建议使用最新稳定版。
  • 操作系统：Windows、macOS 或 Linux 均可。

2. 验证 Go 环境

在终端中运行以下命令，确认 Go 已正确安装并配置：

1
go version

3. 安装 Agent Framework for Go

在你的 Go 项目中，使用 go get 命令来安装框架的核心包：

1
go get github.com/microsoft/agent-framework-go

这个命令会将框架及其主要依赖（如 Azure SDK for Go）添加到你的 go.mod 文件中。

重要提示：Agent Framework for Go 目前处于公共预览阶段。像声明式代理、RAG、CodeAct 和函数式工作流等功能尚不可用，团队正在积极演进。

第二步：创建第一个基础代理

MAF for Go 的主要应用场景之一是连接 Microsoft Foundry 的模型。下面的示例演示了如何创建一个基础代理。

1. 创建项目与主文件

在你的工作目录中，创建一个 main.go 文件。

2. 编写代码

将以下代码复制到 main.go 中。这个代理会连接到 Foundry 端点，并让它写一首关于“Microsoft Agent Framework”的俳句。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
package main

import (
	"cmp"       // Go 1.21+ 的 cmp 包，用于简化默认值处理
	"context"
	"fmt"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

func main() {
	// 1. 从环境变量获取 Foundry 项目端点和模型名称
	endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
	// 如果环境变量未设置，默认使用 "gpt-4o-mini"
	model := cmp.Or(os.Getenv("FOUNDRY_MODEL"), "gpt-4o-mini")

	// 2. 使用 Azure 默认凭证进行身份验证
	//    生产环境建议使用更具体的凭证，如托管标识
	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		panic(err)
	}

	// 3. 创建 Foundry 代理实例
	agent := foundryprovider.NewAgent(
		endpoint,
		credential,
		foundryprovider.ModelDeployment(model),
		foundryprovider.AgentConfig{
			Instructions: "你是一位乐于助人的助手。",
			Name:         "HaikuAgent", // 可选：为代理命名
		},
	)

	// 4. 运行代理并收集响应
	ctx := context.Background()
	response, err := agent.RunText(ctx, "请写一首关于 Microsoft Agent Framework 的俳句。").Collect()
	if err != nil {
		panic(err)
	}

	fmt.Println(response)
}

3. 代码解析

  • 身份验证 (azidentity.NewDefaultAzureCredential)：它按顺序尝试多种 Azure 认证方式（如环境变量、Azure CLI 登录、托管标识等），非常适合本地开发。
  • 代理配置 (foundryprovider.AgentConfig)：你可以在这里设置核心指令（System Prompt）、代理名称等。
  • 运行与收集 (RunText().Collect())：RunText 发送文本请求，Collect() 会等待完整响应返回。

第三步：配置与运行

1. 设置必需的环境变量

在运行前，你需要提供有效的 Foundry 端点。Agent Framework 不会自动加载 .env 文件，因此你需要通过以下方式之一设置环境变量：

方式一：在终端中设置（临时）

  • macOS/Linux:

    1
    2
    3
    export FOUNDRY_PROJECT_ENDPOINT="你的 Foundry 项目端点 URL"
    # 可选，如果不设置，代码会使用默认的 "gpt-4o-mini"
    export FOUNDRY_MODEL="你的模型部署名"

  • Windows (PowerShell):

    1
    2
    $env:FOUNDRY_PROJECT_ENDPOINT="你的 Foundry 项目端点 URL"
    $env:FOUNDRY_MODEL="你的模型部署名"

方式二：使用 az login 进行身份验证

如果使用 DefaultAzureCredential，请确保你已通过 Azure CLI 登录。这能解决大部分身份验证错误。

1
az login

2. 运行代理

配置好环境变量后，在项目根目录下执行：

1
go run main.go

如果一切顺利，你将看到代理生成的俳句文本输出在终端上。

第四步：深入学习与生产化路径

成功运行基础代理后，你可以按照以下路径逐步构建更复杂的应用。

1. 学习路径

官方提供了清晰的循序渐进教程，建议按顺序学习：

步骤 核心概念 说明
1. 第一个代理 基础创建与调用 你已完成这一步。
2. 添加工具 函数调用 (Function Calling) 让代理能调用你定义的函数，例如查询天气、数据库。
3. 多轮对话 会话与状态管理 使用 Session 对象维护对话历史，实现上下文感知。
4. 记忆与持久化 上下文提供者 通过注入持久化上下文，让代理“记住”用户信息。
5. 工作流 多代理编排 构建顺序、并发、条件路由等复杂的工作流。
6. 代理“缰绳” 规划与任务追踪 创建更高级的代理来规划和分解复杂任务。
7. 托管代理 服务化部署 将代理暴露为 HTTP 或 gRPC 服务。

2. 关键诊断工具

  • deeptutor doctor：如果你遇到环境配置问题，这个命令可以检查你的工作空间是否就绪。
  • 故障排除：遇到身份验证错误时，首选方案是运行 az login。对于 API 密钥错误，请检查密钥是否正确且具有相应权限。

总结

通过本教程，你完成了 Microsoft Agent Framework for Go 的环境搭建，并成功运行了第一个基于 Foundry 的代理。核心要点如下：

  • 安装：使用 go get github.com/microsoft/agent-framework-go 安装框架。
  • 核心代码：使用 azidentity.NewDefaultAzureCredential() 进行认证，通过 foundryprovider.NewAgent() 创建代理，并使用 RunText().Collect() 获取响应。
  • 关键现状：该框架处于公共预览阶段，部分高级功能（如 RAG、声明式代理）尚不可用，但核心的代理和工作流编排能力已经具备。
  • 后续步骤：建议按官方教程逐步添加工具、会话、工作流等功能，向生产级应用迈进。