Agent Go SDK

一个功能强大的 Go 框架，用于构建生产就绪的 AI 代理，可将内存管理、工具执行、多模型支持和企业级特性无缝集成到灵活且可扩展的架构中。

文档

📖 docs.goagents.dev — 完整的文档、指南和参考。

社区

加入我们的 Discord 社区，一起协作、分享你的项目，并获得 agent-sdk-go 的社区支持！

特性

核心能力

• 🧠 多模型智能：无缝集成 OpenAI、Anthropic 和 Google Vertex AI（Gemini 模型）。
• 🔧 模块化工具生态：通过即插即用的工具扩展代理能力，支持网络搜索、数据检索和自定义操作。
• 📝 高级内存管理：持久化对话跟踪，提供缓冲区和向量检索选项。
• 🔌 MCP 集成：支持通过 HTTP 和 stdio 传输协议连接 Model Context Protocol (MCP) 服务器。
• 📊 Token 使用追踪：内置 Token 计数功能，用于成本监控、使用分析和优化。

企业级支持

• 🚦 内置安全机制：全面的安全防护措施，确保负责任的 AI 部署。
• 📈 完整可观测性：集成追踪与日志记录功能，便于监控与调试。
• 🏢 企业级多租户支持：安全地为多个组织提供服务，实现资源隔离。

开发体验

• 🛠️ 结构化任务框架：规划、审批并执行复杂的多步骤操作。
• 📄 声明式配置：使用直观的 YAML 定义来构建复杂的代理和任务。
• 🧙 零成本快速启动：根据简单的系统提示自动生成完整的代理配置。

快速入门

前置条件

• Go 1.23+
• Redis（可选，用于分布式内存）

安装

作为 Go 库

将 SDK 添加到你的 Go 项目中：

go get github.com/Ingenimax/agent-sdk-go

作为 CLI 工具（无头 SDK）

选项 1：下载预编译二进制文件（推荐）

从 GitHub Releases 下载适用于你平台的最新版本，并将其添加到你的 PATH 中。

选项 2：通过 Go 安装

go install github.com/Ingenimax/agent-sdk-go/cmd/agent-cli@latest

选项 3：从源码构建

# 克隆仓库
git clone https://github.com/Ingenimax/agent-sdk-go
cd agent-sdk-go

# 构建 CLI 工具
make build-cli

# 安装到系统 PATH（可选）
make install

CLI 快速启动：

# 初始化配置
agent-cli init

# 选项 1：设置环境变量
export OPENAI_API_KEY=your_api_key_here

# 选项 2：使用 .env 文件（推荐）
cp env.example .env
# 编辑 .env 文件以填写你的 API 密钥

# 运行简单查询
agent-cli run "旧金山的天气如何？"

# 启动交互式聊天
agent-cli chat

配置

SDK 使用环境变量进行配置。关键变量包括：

• OPENAI_API_KEY：你的 OpenAI API 密钥
• OPENAI_MODEL：要使用的模型（例如 gpt-4o-mini）
• LOG_LEVEL：日志级别（debug、info、warn、error）
• REDIS_ADDRESS：Redis 服务器地址（如果使用 Redis 作为内存存储）

完整配置选项请参阅 .env.example 文件。

获取 Nina（AI 助手）的帮助

Nina 是一位对 agent-sdk-go 代码库了如指掌的 AI 助手。通过 MCP（Model Context Protocol）连接 Nina，即可在你的 IDE 中直接获得帮助。

Cursor IDE

将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "agent-sdk-go": {
      "url": "https://nina.agentgogo.app/mcp",
      "transport": "sse"
    }
  }
}

重启 Cursor IDE 后，Nina 的工具将出现在你的 AI 助手中。

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

平台	配置位置
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-sdk-go": {
      "url": "https://nina.agentgogo.app/mcp",
      "transport": "sse"
    }
  }
}

重启 Claude Desktop 后，Nina 的工具将通过 🔌 图标提供服务。

可用工具

工具	描述
ask_nina	提问关于 agent-sdk-go、Go 编程或开发的问题
search_sdk	搜索 SDK 文档和源代码
get_sdk_status	获取 Nina 的 SDK 知识库状态

使用示例

创建一个简单的智能体

package main

import (
	"context"
	"fmt"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/config"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
	"github.com/Ingenimax/agent-sdk-go/pkg/logging"
	"github.com/Ingenimax/agent-sdk-go/pkg/memory"
	"github.com/Ingenimax/agent-sdk-go/pkg/multitenancy"
	"github.com/Ingenimax/agent-sdk-go/pkg/tools"
	"github.com/Ingenimax/agent-sdk-go/pkg/tools/websearch"
)

func main() {
	// 创建日志记录器
	logger := logging.New()

	// 获取配置
	cfg := config.Get()

	// 使用 OpenAI 创建一个新的智能体
	openaiClient := openai.NewClient(cfg.LLM.OpenAI.APIKey,
		openai.WithLogger(logger))

	agent, err := agent.NewAgent(
		agent.WithLLM(openaiClient),
		agent.WithMemory(memory.NewConversationBuffer()),
		agent.WithTools(createTools(logger).List()...),
		agent.WithSystemPrompt("你是一位有用的 AI 助手。当你不知道答案或需要实时信息时，可以使用可用工具来查找信息。"),
		agent.WithName("ResearchAssistant"),
	)
	if err != nil {
		logger.Error(context.Background(), "创建智能体失败", map[string]interface{}{"error": err.Error()})
		return
	}

	// 创建包含组织 ID 和对话 ID 的上下文
	ctx := context.Background()
	ctx = multitenancy.WithOrgID(ctx, "default-org")
	ctx = context.WithValue(ctx, memory.ConversationIDKey, "conversation-123")

	// 运行智能体
	response, err := agent.Run(ctx, "旧金山的天气如何？")
	if err != nil {
		logger.Error(ctx, "运行智能体失败", map[string]interface{}{"error": err.Error()})
		return
	}

	fmt.Println(response)
}

func createTools(logger logging.Logger) *tools.Registry {
	// 获取配置
	cfg := config.Get()

	// 创建工具注册表
	toolRegistry := tools.NewRegistry()

	// 如果有 API 密钥，则添加网络搜索工具
	if cfg.Tools.WebSearch.GoogleAPIKey != "" && cfg.Tools.WebSearch.GoogleSearchEngineID != "" {
		searchTool := websearch.New(
			cfg.Tools.WebSearch.GoogleAPIKey,
			cfg.Tools.WebSearch.GoogleSearchEngineID,
		)
		toolRegistry.Register(searchTool)
	}

	return toolRegistry
}

令牌使用跟踪

SDK 提供了内置的令牌使用跟踪功能，用于成本监控和使用情况分析。你可以通过详细生成方法访问令牌信息：

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Ingenimax/agent-sdk-go/pkg/llm/anthropic"
)

func main() {
	// 创建 LLM 客户端
	client := anthropic.NewClient("your-api-key",
		anthropic.WithModel("claude-3-haiku-20240307"),
	)

	ctx := context.Background()
	prompt := "用一段话解释量子计算。"

	// 传统方法（向后兼容）
	content, err := client.Generate(ctx, prompt)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("响应：%s\n", content)

	// 新的详细方法，包含令牌使用情况
	response, err := client.GenerateDetailed(ctx, prompt)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("响应：%s\n", response.Content)
	fmt.Printf("模型：%s\n", response.Model)

	if response.Usage != nil {
		fmt.Printf("令牌使用情况：\n")
		fmt.Printf("  输入令牌： %d\n", response.Usage.InputTokens)
		fmt.Printf("  输出令牌： %d\n", response.Usage.OutputTokens)
		fmt.Printf("  总令牌： %d\n", response.Usage.TotalTokens)

		// 计算预估成本（根据实际定价调整）
		inputCost := float64(response.Usage.InputTokens) * 0.25 / 1000000
		outputCost := float64(response.Usage.OutputTokens) * 1.25 / 1000000
		fmt.Printf("  预估成本：$%.6f\n", inputCost + outputCost)
	}
}

可用方法：

• Generate() - 传统方法，返回字符串（未更改）
• GenerateDetailed() - 新方法，返回包含使用信息的 *LLMResponse
• GenerateWithTools() - 传统方法，支持工具调用（未更改）
• GenerateWithToolsDetailed() - 新方法，支持工具调用并提供使用信息

提供商支持：

• ✅ Anthropic：完全支持令牌使用跟踪
• ✅ OpenAI：完全支持，包括推理令牌
• ✅ Azure OpenAI：完全支持（与 OpenAI 类似）
• ❌ Ollama/vLLM：本地模型不提供使用数据（Usage=nil）

完整的演示请参阅 令牌使用示例。

高级 YAML 配置

SDK 现在支持基于 YAML 的全面代理配置，具备行为设置、工具配置、MCP 集成、子代理以及环境变量扩展等高级功能。

示例：使用 YAML 配置的完整代理

package main

import (
	"context"
	"log"
	"os"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
)

func main() {
	// 创建 LLM 客户端
	llm := openai.NewClient(os.Getenv("OPENAI_API_KEY"))

	// 从 YAML 文件加载代理配置
	configs, err := agent.LoadAgentConfigsFromFile("agents.yaml")
	if err != nil {
		log.Fatal(err)
	}

	// 直接从配置创建代理
	agentInstance, err := agent.NewAgentFromConfig("research_assistant", configs, nil, agent.WithLLM(llm))
	if err != nil {
		log.Fatal(err)
	}

	// 运行代理
	result, err := agentInstance.Run(context.Background(), "可再生能源领域的最新进展是什么？")
	if err != nil {
		log.Fatal(err)
	}

	println(result)
}

agents.yaml（高级配置）：

research_assistant:
  role: "高级研究助理"
  goal: "提供全面的研究与分析"
  backstory: "拥有多种数据源和专业子代理的专家研究员"

  # 行为设置
  max_iterations: 15
  require_plan_approval: false

  # LLM 配置
  llm_config:
    temperature: 0.7
    enable_reasoning: true
    reasoning_budget: 20000

  # 内置及自定义工具
  tools:
    - type: "builtin"
      name: "websearch"
      enabled: true
      config:
        api_key: "${SEARCH_API_KEY}"
        engine: "brave"

    - type: "builtin"
      name: "calculator"
      enabled: true

  # MCP 服务器集成
  mcp:
    mcpServers:
      filesystem:
        command: "npx"
        args: ["-y", "@modelcontextprotocol/server-filesystem", "."]

      database:
        command: "python"
        args: ["-m", "mcp_server_database"]
        env:
          DATABASE_URL: "${DATABASE_URL}"

  # 内存配置
  memory:
    type: "redis"
    config:
      address: "${REDIS_ADDRESS}"
      db: 0

  # 用于专项任务的子代理
  sub_agents:
    data_analyzer:
      role: "数据分析专家"
      goal: "分析复杂数据集并提供洞察"
      backstory: "擅长统计分析和数据可视化"
      max_iterations: 8
      llm_config:
        temperature: 0.3

    report_writer:
      role: "技术文档撰写员"
      goal: "撰写综合性报告和文档"
      backstory: "善于将复杂数据转化为清晰的报告"
      tools:
        - type: "builtin"
          name: "text_processor"
          enabled: true

  # 运行时设置
  runtime:
    log_level: "info"
    enable_tracing: true
    timeout: "300s"

高级 YAML 配置的关键特性：

• 环境变量扩展：使用 ${VAR} 语法处理敏感数据
• 行为设置：配置迭代次数、计划审批要求及运行时行为
• LLM 配置：微调温度、推理能力及模型特定参数
• 工具集成：以声明式方式配置内置工具、自定义工具、MCP 工具及代理工具
• 子代理：构建具有专业化能力的层级化代理结构
• 内存后端：配置缓冲区、Redis 或向量存储等内存系统
• MCP 集成：无缝配置 Model Context Protocol 服务器
• 结构化响应：定义 JSON 模式以确保输出格式一致

使用 YAML 配置创建代理（基础）

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"path/filepath"
	"strings"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
)

func main() {
	// 从环境变量获取 OpenAI API 密钥
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		log.Fatal("未提供 OpenAI API 密钥。请设置 OPENAI_API_KEY 环境变量。")
	}

	// 创建 LLM 客户端
	llm := openai.NewClient(apiKey)

	// 加载代理配置
	agentConfigs, err := agent.LoadAgentConfigsFromFile("agents.yaml")
	if err != nil {
		log.Fatalf("加载代理配置失败：%v", err)
	}

	// 加载任务配置
	taskConfigs, err := agent.LoadTaskConfigsFromFile("tasks.yaml")
	if err != nil {
		log.Fatalf("加载任务配置失败：%v", err)
	}

	// 创建用于模板替换的变量映射
	variables := map[string]string{
		"topic": "人工智能",
	}

	// 为特定任务创建代理
	taskName := "research_task"
	agent, err := agent.CreateAgentForTask(taskName, agentConfigs, taskConfigs, variables, agent.WithLLM(llm))
	if err != nil {
		log.Fatalf("为任务创建代理失败：%v", err)
	}

	// 执行任务
	fmt.Printf("正在执行主题为 '%s' 的任务...\n", variables["topic"])
	result, err := agent.ExecuteTaskFromConfig(context.Background(), taskName, taskConfigs, variables)
	if err != nil {
		log.Fatalf("执行任务失败：%v", err)
	}

	// 打印结果
	fmt.Println("\n任务结果：")
	fmt.Println(result)
}

YAML 配置示例：

agents.yaml：

researcher:
  role: >
    {topic} 高级数据研究员
  goal: >
    探索 {topic} 领域的前沿发展
  backstory: >
    您是一位经验丰富的研究员，擅长挖掘 {topic} 领域的最新动态。以能够找到最相关的信息并以清晰简洁的方式呈现而闻名。
  
reporting_analyst:
  role: >
    {topic} 报告分析师
  goal: >
    基于 {topic} 数据分析和研究成果，撰写详细报告
  backstory: >
    您是一位细致入微的分析师，对细节有着敏锐的洞察力。您以能够将复杂数据转化为清晰简洁的报告而著称，使他人易于理解并采取行动。

tasks.yaml：

research_task:
  description: >
    对 {topic} 进行全面研究
    确保在 2025 年这一背景下，找到所有有趣且相关的信息。
  expected_output: >
    关于 {topic} 的 10 条要点列表
  agent: researcher

reporting_task:
  description: >
    审阅您所获得的背景信息，并将每个主题扩展为报告中的完整章节。
    确保报告内容详尽，涵盖所有相关信息。
  expected_output: >
    一份完整的报告，包含主要主题及其详细信息。
    格式为 Markdown，不含 '```'
  agent: reporting_analyst
  output_file: "{topic}_report.md"

使用 YAML 配置的结构化输出

SDK 支持直接在 YAML 配置文件中定义结构化输出（JSON 响应）。这使得您可以在从 YAML 创建代理时自动应用结构化输出，并将响应直接反序列化为 Go 结构体。

包含结构化输出的 agents.yaml:

researcher:
  role: >
    {topic} 高级数据研究员
  goal: >
    探索 {topic} 领域的前沿发展
  backstory: >
    您是一位经验丰富的研究员，擅长挖掘 {topic} 领域的最新进展。以能够找到最相关的信息并以清晰简洁的方式呈现而闻名。
  response_format:
    type: "json_object"
    schema_name: "ResearchResult"
    schema_definition:
      type: "object"
      properties:
        findings:
          type: "array"
          items:
            type: "object"
            properties:
              title:
                type: "string"
                description: "发现的标题"
              description:
                type: "string"
                description: "详细描述"
              source:
                type: "string"
                description: "信息来源"
        summary:
          type: "string"
          description: "发现的执行摘要"
        metadata:
          type: "object"
          properties:
            total_findings:
              type: "integer"
            research_date:
              type: "string"

包含结构化输出的 tasks.yaml:

research_task:
  description: >
    对 {topic} 进行全面研究
    确保找到任何有趣且相关的信息。
  expected_output: >
    包含发现、摘要和元数据的结构化 JSON 响应
  agent: researcher
  output_file: "{topic}_report.json"
  response_format:
    type: "json_object"
    schema_name: "ResearchResult"
    schema_definition:
      # 与上面相同的模式

在 Go 代码中的用法:

// 定义与 YAML 模式匹配的 Go 结构体
type ResearchResult struct {
    Findings []struct {
        Title       string `json:"title"`
        Description string `json:"description"`
        Source      string `json:"source"`
    } `json:"findings"`
    Summary  string `json:"summary"`
    Metadata struct {
        TotalFindings int    `json:"total_findings"`
        ResearchDate  string `json:"research_date"`
    } `json:"metadata"`
}

// 创建代理并执行任务
agent, err := agent.CreateAgentForTask("research_task", agentConfigs, taskConfigs, variables, agent.WithLLM(llm))
result, err := agent.ExecuteTaskFromConfig(context.Background(), "research_task", taskConfigs, variables)

// 反序列化结构化输出
var structured ResearchResult
err = json.Unmarshal([]byte(result), &structured)

更多详情，请参阅 使用 YAML 配置的结构化输出。

自动生成代理配置

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/config"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
)

func main() {
	// 加载配置
	cfg := config.Get()

	// 创建 LLM 客户端
	openaiClient := openai.NewClient(cfg.LLM.OpenAI.APIKey)

	// 根据系统提示自动生成配置创建代理
	agent, err := agent.NewAgentWithAutoConfig(
		context.Background(),
		agent.WithLLM(openaiClient),
		agent.WithSystemPrompt("您是一位旅行顾问，帮助用户规划旅行和度假。您擅长寻找隐藏的宝藏，并根据旅客的偏好制定个性化行程。"),
		agent.WithName("旅行助手"),
	)
	if err != nil {
		panic(err)
	}

	// 获取生成的配置
	agentConfig := agent.GetGeneratedAgentConfig()
	taskConfigs := agent.GetGeneratedTaskConfigs()

	// 打印生成的代理详情
	fmt.Printf("生成的代理角色： %s\n", agentConfig.Role)
	fmt.Printf("生成的代理目标： %s\n", agentConfig.Goal)
	fmt.Printf("生成的代理背景故事： %s\n", agentConfig.Backstory)

	// 打印生成的任务
	fmt.Println("\n生成的任务：")
	for taskName, taskConfig := range taskConfigs {
		fmt.Printf("- %s: %s\n", taskName, taskConfig.Description)
	}

	// 将生成的配置保存为 YAML 文件
	agentConfigMap := map[string]agent.AgentConfig{
		"旅行助手": *agentConfig,
	}

	// 保存代理配置到文件
	agentYaml, _ := os.Create("agent_config.yaml")
	defer agentYaml.Close()
	agent.SaveAgentConfigsToFile(agentConfigMap, agentYaml)

	// 保存任务配置到文件
	taskYaml, _ := os.Create("task_config.yaml")
	defer taskYaml.Close()
	agent.SaveTaskConfigsToFile(taskConfigs, taskYaml)

	// 使用自动生成的代理
	response, err := agent.Run(context.Background(), "我想计划一次为期三天的东京之旅。")
	if err != nil {
		panic(err)
	}
	fmt.Println(response)
}

自动生成配置功能利用 LLM 推理，从简单的系统提示中推导出完整的代理档案及其相关任务。生成的配置包括：

• 代理档案：定义代理人格的角色、目标和背景故事
• 任务定义：代理可以执行的专业化任务，附有描述和预期输出
• 可重用 YAML：保存配置以便在其他应用程序中重复使用

这种方法大大减少了创建专业化代理所需的工作量，同时确保了配置的一致性和质量。

使用带有代理的 MCP 服务器

SDK 支持 立即初始化 和 延迟初始化 的 MCP 服务器：

• 立即初始化：MCP 服务器在代理创建时即被初始化
• 延迟初始化：MCP 服务器仅在其工具首次被调用时才被初始化（推荐）

延迟初始化的 MCP 集成（推荐）

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
	"github.com/Ingenimax/agent-sdk-go/pkg/memory"
)

func main() {
	// 创建 OpenAI LLM 客户端
	apiKey := os.Getenv("OPENAI_API_KEY")
	llm := openai.NewClient(apiKey, openai.WithModel("gpt-4o-mini"))

	// 定义延迟初始化的 MCP 配置
	// 注意：CLI 支持动态工具发现，但 SDK 需要显式定义工具
	lazyMCPConfigs := []agent.LazyMCPConfig{
		{
			Name:    "aws-api-server",
			Type:    "stdio",
			Command: "docker",
			Args:    []string{"run", "--rm", "-i", "public.ecr.aws/awslabs-mcp/awslabs/aws-api-mcp-server:latest"},
			Env:     []string{"AWS_REGION=us-west-2"},
			Tools: []agent.LazyMCPToolConfig{
				{
					Name:        "suggest_aws_commands",
					Description: "根据自然语言建议 AWS CLI 命令",
					Schema:      map[string]interface{}{"type": "object", "properties": map[string]interface{}{"query": map[string]interface{}{"type": "string"}}},
				},
			},
		},
		{
			Name:    "kubectl-ai",
			Type:    "stdio",
			Command: "kubectl-ai",
			Args:    []string{"--mcp-server"},
			Tools: []agent.LazyMCPToolConfig{
				{
					Name:        "kubectl",
					Description: "对 Kubernetes 集群执行 kubectl 命令",
					Schema:      map[string]interface{}{"type": "object", "properties": map[string]interface{}{"command": map[string]interface{}{"type": "string"}}},
				},
			},
		},
	}

	// 创建带有延迟初始化 MCP 配置的代理
	myAgent, err := agent.NewAgent(
		agent.WithLLM(llm),
		agent.WithLazyMCPConfigs(lazyMCPConfigs),
		agent.WithMemory(memory.NewConversationBuffer()),
		agent.WithSystemPrompt("你是一位可以访问 AWS 和 Kubernetes 工具的 AI 助手。"),
	)
	if err != nil {
		log.Fatalf("创建代理失败：%v", err)
	}

	// 使用代理 - MCP 服务器将在首次使用工具时初始化
	response, err := myAgent.Run(context.Background(), "列出我的 EC2 实例并显示集群中的 Pod")
	if err != nil {
		log.Fatalf("运行代理失败：%v", err)
	}

	fmt.Println("代理响应：", response)
}

立即初始化的 MCP 集成

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/interfaces"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
	"github.com/Ingenimax/agent-sdk-go/pkg/mcp"
	"github.com/Ingenimax/agent-sdk-go/pkg/memory"
	"github.com/Ingenimax/agent-sdk-go/pkg/multitenancy"
)

func main() {
	logger := log.New(os.Stderr, "AGENT: ", log.LstdFlags)

	// 创建 OpenAI LLM 客户端
	apiKey := os.Getenv("OPENAI_API_KEY")
	if apiKey == "" {
		logger.Fatal("请设置 OPENAI_API_KEY 环境变量。")
	}
	llm := openai.NewClient(apiKey, openai.WithModel("gpt-4o-mini"))

	// 创建 MCP 服务器
	var mcpServers []interfaces.MCPServer

	// 连接到基于 HTTP 的 MCP 服务器
	httpServer, err := mcp.NewHTTPServer(context.Background(), mcp.HTTPServerConfig{
		BaseURL: "http://localhost:8083/mcp",
	})
	if err != nil {
		logger.Printf("警告：初始化 HTTP MCP 服务器失败：%v", err)
	} else {
		mcpServers = append(mcpServers, httpServer)
		logger.Println("成功初始化 HTTP MCP 服务器。")
	}

	// 连接到基于 stdio 的 MCP 服务器
	stdioServer, err := mcp.NewStdioServer(context.Background(), mcp.StdioServerConfig{
		Command: "go",
		Args:    []string{"run", "./server-stdio/main.go"},
	})
	if err != nil {
		logger.Printf("警告：初始化 STDIO MCP 服务器失败：%v", err)
	} else {
		mcpServers = append(mcpServers, stdioServer)
		logger.Println("成功初始化 STDIO MCP 服务器。")
	}

	// 创建支持 MCP 服务器的代理
	myAgent, err := agent.NewAgent(
		agent.WithLLM(llm),
		agent.WithMCPServers(mcpServers),
		agent.WithMemory(memory.NewConversationBuffer()),
		agent.WithSystemPrompt("你是一位可以使用 MCP 服务器工具的 AI 助手。"),
		agent.WithName("MCPAgent"),
	)
	if err != nil {
		logger.Fatalf("创建代理失败：%v", err)
	}

	// 创建包含组织和对话 ID 的上下文
	ctx := context.Background()
	ctx = multitenancy.WithOrgID(ctx, "default-org")
	ctx = context.WithValue(ctx, memory.ConversationIDKey, "mcp-demo")

	// 运行将使用 MCP 工具的代理
	response, err := myAgent.Run(ctx, "现在几点了？")
	if err != nil {
		logger.Fatalf("代理运行失败：%v", err)
	}

	fmt.Println("代理响应：", response)
}

架构

该 SDK 采用模块化架构，包含以下关键组件：

• 代理：协调 LLM、记忆和工具
• LLM：与语言模型提供商（OpenAI、Anthropic、Google Vertex AI）的接口
• 记忆：存储对话历史和上下文
• 工具：扩展代理的能力
• 向量存储：用于语义搜索和检索
• 护栏：确保安全且负责任的 AI 使用
• 执行计划：管理复杂任务的规划、审批和执行
• 配置：基于 YAML 的代理和任务定义

支持的 LLM 提供商

• OpenAI：GPT-4、GPT-3.5 及其他 OpenAI 模型
• Anthropic：Claude 3.5 Sonnet、Claude 3 Haiku 及其他 Claude 模型
• DeepSeek：DeepSeek-V3.2 对话和推理模型
  • 原生工具/函数调用支持
  • 具有缓存优化的成本效益定价
  • 128K 令牌上下文窗口
  • 推理模式下可生成高达 64K 输出令牌
  • 功能与 OpenAI/Anthropic 完全对等
• Google Vertex AI：Gemini 1.5 Pro、Gemini 1.5 Flash、Gemini 2.0 Flash 及 Gemini Pro Vision
  • 先进的推理模式（无、最小、全面）
  • 具备视觉模型的多模态能力
  • 函数调用和工具集成
  • 灵活的身份验证方式（ADC 或服务账户文件）
• Ollama：本地 LLM 服务器，支持多种开源模型
  • 无需外部 API 调用即可在本地运行模型
  • 支持 Llama2、Mistral、CodeLlama 等模型
  • 模型管理功能（列出、拉取、切换模型）
  • 本地处理以降低延迟并保护隐私
• vLLM：高性能本地 LLM 推理，采用 PagedAttention 技术
  • 针对 CUDA 加速的 GPU 推理进行了优化
  • 高效的内存管理，适用于大型模型
  • 支持 Llama2、Mistral、CodeLlama 等模型
  • 模型管理功能（列出、拉取、切换模型）
  • 本地处理以降低延迟并保护隐私

CLI 工具（无头 SDK）

Agent SDK 包含一个功能强大的命令行界面，可用于无头使用：

CLI 功能

• 🤖 多模型提供商支持：OpenAI、Anthropic、DeepSeek、Google Vertex AI、Ollama、vLLM
• 💬 交互式聊天模式：实时对话，具备持久化记忆
• 📝 任务执行：从 YAML 配置中运行预定义任务
• 🎨 自动配置：根据简单提示生成智能体配置
• 🔧 灵活配置：基于 JSON 的配置，并支持环境变量
• 🛠️ 丰富的工具集成：网络搜索、GitHub、MCP 服务器等
• 🔌 MCP 服务器管理：添加、列出、移除和测试 MCP 服务器
• 📄 .env 文件支持：自动加载 .env 文件中的环境变量

CLI 命令

# 初始化配置
agent-cli init

# 使用单个提示运行智能体
agent-cli run "用通俗易懂的语言解释量子计算"

# 直接执行（无需设置）
agent-cli --prompt "2+2 等于多少？"

# 使用 MCP 服务器直接执行
agent-cli --prompt "列出我的 EC2 实例" \
  --mcp-config ./aws_api_server.json \
  --allowedTools "mcp__aws__suggest_aws_commands,mcp__aws__call_aws" \
  --dangerously-skip-permissions

# 执行预定义任务
agent-cli task --agent-config=agents.yaml --task-config=tasks.yaml --task=research_task --topic="AI"

# 启动交互式聊天
agent-cli chat

# 根据系统提示生成配置
agent-cli generate --prompt="你是一名旅游顾问" --output=./configs

# 列出可用资源
agent-cli list providers
agent-cli list models
agent-cli list tools

# 管理配置
agent-cli config show
agent-cli config set provider anthropic

# 管理 MCP 服务器
agent-cli mcp add --type=http --url=http://localhost:8083/mcp --name=my-server
agent-cli mcp list
agent-cli mcp remove --name=my-server

# 从 JSON 配置导入/导出 MCP 服务器
agent-cli mcp import --file=mcp-servers.json
agent-cli mcp export --file=mcp-servers.json

# 使用 MCP 服务器并过滤工具的直接执行
agent-cli --prompt "列出我的 EC2 实例" \
  --mcp-config ./aws_api_server.json \
  --allowedTools "suggest_aws_commands,call_aws" \
  --dangerously-skip-permissions

# 使用 kubectl-ai 进行 Kubernetes 管理
agent-cli --prompt "列出 default 命名空间下的所有 Pod" \
  --mcp-config ./kubectl_ai.json \
  --allowedTools "kubectl" \
  --dangerously-skip-permissions

高级 MCP 功能

CLI 现在支持 动态工具发现 和 灵活的工具过滤：

• 无硬编码工具：MCP 服务器自行定义其工具和架构
• 动态发现：工具在 MCP 服务器首次初始化时被发现
• 灵活过滤：使用 --allowedTools 指定可使用的具体工具
• JSON 配置：从外部 JSON 文件加载 MCP 服务器配置
• 环境变量：每个 MCP 服务器可以指定自定义环境变量

热门 MCP 服务器：

• AWS API 服务器：AWS CLI 操作及建议
• kubectl-ai：通过自然语言管理 Kubernetes 集群
• 文件系统服务器：文件系统操作与管理
• 数据库服务器：SQL 查询执行及数据库操作

CLI 文档

完整的 CLI 文档请参阅：CLI README

示例

请查看 cmd/examples 目录以获取完整示例：

• 简单智能体：带有系统提示的基本智能体
• YAML 配置：使用 YAML 定义智能体和任务
• 自动配置：根据系统提示生成智能体配置
• 智能体配置向导：交互式 CLI，用于创建和使用智能体
• MCP 集成：将 Model Context Protocol 服务器与智能体结合使用
• 多 LLM 支持：使用 OpenAI、Azure OpenAI、Anthropic 和 Vertex AI 的示例
• Vertex AI 集成：包含 Gemini 模型、推理模式和工具的全面示例

LLM 提供商示例

• examples/llm/openai/：OpenAI 集成示例
• examples/llm/azureopenai/：基于部署配置的 Azure OpenAI 集成示例
• examples/llm/anthropic/：Anthropic Claude 集成示例
• examples/llm/ollama/：本地 Ollama LLM 集成示例
• examples/llm/vllm/：高性能本地 vLLM 集成示例

Agent GoGo - 快速部署基于本 SDK 的智能体

• 自行托管或通过我们的 Cloud Gateway 启动您的智能体。访问 https://agentgogo.app 了解更多信息。

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

文档

📖 完整文档可在 docs.goagents.dev 查阅

如需更详细的信息，您还可以参考以下文档：

• 环境变量
• 记忆
• 追踪
• 向量存储
• 数据存储 - PostgreSQL 和 Supabase 集成，用于结构化数据
• LLM
• 多租户
• 任务
• 工具
• 智能体
• 执行计划
• 护栏
• MCP

agent-sdk-go 快速上手指南

agent-sdk-go 是一个强大的 Go 语言框架，专为构建生产级 AI 智能体设计。它无缝集成了内存管理、工具执行、多模型支持（OpenAI, Anthropic, Google Vertex AI）以及企业级特性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Go 版本: 1.23 或更高版本
• 可选依赖: Redis（如果您需要使用分布式内存功能）

安装步骤

您可以选择将 SDK 作为 Go 库引入项目，或者作为命令行工具（CLI）使用。

方式一：作为 Go 库安装

在项目目录中运行以下命令添加依赖：

go get github.com/Ingenimax/agent-sdk-go

方式二：作为 CLI 工具安装（无头模式）

推荐下载预编译二进制文件，也可通过 Go 安装。

选项 1：下载预编译二进制文件（推荐） 访问 GitHub Releases 下载适合您平台的最新版本，并将其添加到系统 PATH 中。

选项 2：通过 Go 安装

go install github.com/Ingenimax/agent-sdk-go/cmd/agent-cli@latest

选项 3：从源码构建

# 克隆仓库
git clone https://github.com/Ingenimax/agent-sdk-go
cd agent-sdk-go

# 构建 CLI 工具
make build-cli

# (可选) 安装到系统 PATH
make install

基本使用

1. 配置环境变量

SDK 主要通过环境变量进行配置。您可以复制示例文件并编辑，或直接导出变量。

使用 .env 文件（推荐）：

cp env.example .env
# 编辑 .env 文件，填入您的 API Key

关键配置项：

• OPENAI_API_KEY: 您的 OpenAI API 密钥
• OPENAI_MODEL: 使用的模型名称 (例如：gpt-4o-mini)
• LOG_LEVEL: 日志级别 (debug, info, warn, error)
• REDIS_ADDRESS: Redis 地址（如需使用 Redis 内存）

2. CLI 快速体验

安装完成后，您可以立即运行简单查询或进入交互模式：

# 初始化配置
agent-cli init

# 运行单次查询
agent-cli run "What's the weather in San Francisco?"

# 启动交互式聊天
agent-cli chat

3. 代码示例：创建简单智能体

以下是一个最小的 Go 代码示例，展示如何初始化一个具备记忆和工具能力的智能体：

package main

import (
	"context"
	"fmt"

	"github.com/Ingenimax/agent-sdk-go/pkg/agent"
	"github.com/Ingenimax/agent-sdk-go/pkg/config"
	"github.com/Ingenimax/agent-sdk-go/pkg/llm/openai"
	"github.com/Ingenimax/agent-sdk-go/pkg/logging"
	"github.com/Ingenimax/agent-sdk-go/pkg/memory"
	"github.com/Ingenimax/agent-sdk-go/pkg/multitenancy"
	"github.com/Ingenimax/agent-sdk-go/pkg/tools"
)

func main() {
	// 创建日志记录器
	logger := logging.New()
	cfg := config.Get()

	// 初始化 OpenAI 客户端
	openaiClient := openai.NewClient(cfg.LLM.OpenAI.APIKey,
		openai.WithLogger(logger))

	// 创建智能体
	agentInstance, err := agent.NewAgent(
		agent.WithLLM(openaiClient),
		agent.WithMemory(memory.NewConversationBuffer()),
		agent.WithTools(tools.NewRegistry().List()...),
		agent.WithSystemPrompt("You are a helpful AI assistant."),
		agent.WithName("MyAssistant"),
	)
	if err != nil {
		logger.Error(context.Background(), "Failed to create agent", map[string]interface{}{"error": err.Error()})
		return
	}

	// 设置上下文（包含组织 ID 和会话 ID）
	ctx := context.Background()
	ctx = multitenancy.WithOrgID(ctx, "default-org")
	ctx = context.WithValue(ctx, memory.ConversationIDKey, "conversation-123")

	// 运行智能体
	response, err := agentInstance.Run(ctx, "Hello, who are you?")
	if err != nil {
		logger.Error(ctx, "Failed to run agent", map[string]interface{}{"error": err.Error()})
		return
	}

	fmt.Println(response)
}

进阶提示：YAML 配置

对于复杂的智能体编排，SDK 支持通过 YAML 文件声明式地定义智能体行为、工具链和子智能体。您可以使用 agent.LoadAgentConfigsFromFile 加载配置，并通过 agent.NewAgentFromConfig 直接实例化，无需编写大量样板代码。详细配置请参考官方文档。