Speelka Agent

基于模型上下文协议 (MCP) 的通用 LLM 代理，能够利用来自其他 MCP 服务器的工具。

flowchart TB
    User["任何 MCP 客户端"] --> |"1. 请求"| Agent["Speelka Agent"]
    Agent --> |"2. 格式化提示"| LLM["LLM 服务"]
    LLM --> |"3. 工具调用"| Agent
    Agent --> |"4. 执行工具"| Tools["外部 MCP 工具"]
    Tools --> |"5. 返回结果"| Agent
    Agent --> |"6. 处理重复"| LLM
    Agent --> |"7. 最终答案"| User

主要特性

• 精确的代理定义: 通过提示工程定义详细的代理行为
• 客户端上下文优化: 减少客户端的上下文大小，以提高令牌使用效率
• LLM 灵活性: 在客户端和代理端之间使用不同的 LLM 提供商
• 集中式工具管理: 所有可用工具的单一控制点
• 多种集成选项: 支持 MCP stdio、MCP HTTP 和 Simple HTTP API
• 内置可靠性: 用于处理瞬时故障的重试机制
• 可扩展性: 无需客户端更改即可扩展系统行为
• MCP 感知日志记录: 具有 MCP 通知的结构化日志记录
• 令牌管理: 自动令牌计数和历史压缩
• 灵活的配置: 支持环境变量、YAML 和 JSON 配置文件

快速开始

前提条件

• Go 1.19 或更高版本
• LLM API 凭据 (OpenAI 或 Anthropic)
• 外部 MCP 工具 (可选)

安装

git clone https://github.com/korchasa/speelka-agent-go.git
cd speelka-agent-go
go build ./cmd/server

配置

可以使用 YAML、JSON 或环境变量提供配置。

注意: ./examples 目录已弃用，将在未来版本中删除。请改用 ./site/examples 目录中的示例。

示例配置文件位于 site/examples 目录中：

• site/examples/simple.yaml: YAML 格式的基本代理配置（首选）
• site/examples/ai-news.yaml: YAML 格式的 AI 新闻代理配置（首选）
• site/examples/simple.json: JSON 格式的基本代理配置
• site/examples/simple.env: 作为环境变量的基本代理配置

这是一个简单的 YAML 配置示例：

agent:
  name: "simple-speelka-agent"
  version: "1.0.0"

  # 工具配置
  tool:
    name: "process"
    description: "用于使用 LLM 处理用户查询的处理工具"
    argument_name: "input"
    argument_description: "要处理的用户查询"

  # LLM 配置
  llm:
    provider: "openai"
    api_key: ""  # 为了安全起见，通过环境变量设置
    model: "gpt-4o"
    temperature: 0.7
    prompt_template: "你是一个乐于助人的 AI 助手。 回应以下请求：{{input}}。 提供详细且有用的回复。 可用工具：{{tools}}"

  # MCP 服务器连接
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]

      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]

# 运行时配置
runtime:
  log:
    level: "info"

  transports:
    stdio:
      enabled: true

使用环境变量

所有环境变量都以 SPL_ 为前缀：

环境变量	默认值	描述
代理配置
SPL_AGENT_NAME	必需	代理的名称
SPL_AGENT_VERSION	"1.0.0"	代理的版本
工具配置
SPL_TOOL_NAME	必需	代理提供的工具的名称
SPL_TOOL_DESCRIPTION	必需	工具功能的描述
SPL_TOOL_ARGUMENT_NAME	必需	工具的参数名称
SPL_TOOL_ARGUMENT_DESCRIPTION	必需	工具参数的描述
LLM 配置
SPL_LLM_PROVIDER	必需	LLM 服务的提供商（例如，“openai”、“anthropic”）
SPL_LLM_API_KEY	必需	LLM 提供商的 API 密钥
SPL_LLM_MODEL	必需	模型名称（例如，“gpt-4o”、“claude-3-opus-20240229”）
SPL_LLM_MAX_TOKENS	0	要生成的最大令牌数（0 表示无限制）
SPL_LLM_TEMPERATURE	0.7	用于生成随机性的温度参数
SPL_LLM_PROMPT_TEMPLATE	必需	系统提示的模板（必须包含与 SPL_TOOL_ARGUMENT_NAME 值和 {{tools}} 匹配的占位符）
聊天配置
SPL_CHAT_MAX_ITERATIONS	25	LLM 的最大迭代次数
SPL_CHAT_MAX_TOKENS	0	聊天历史记录中的最大令牌数（0 表示基于模型）
SPL_CHAT_COMPACTION_STRATEGY	"delete-old"	用于压缩聊天历史记录的策略（“delete-old”、“delete-middle”）
LLM 重试配置
SPL_LLM_RETRY_MAX_RETRIES	3	LLM API 调用的最大重试次数
SPL_LLM_RETRY_INITIAL_BACKOFF	1.0	初始退避时间（秒）
SPL_LLM_RETRY_MAX_BACKOFF	30.0	最大退避时间（秒）
SPL_LLM_RETRY_BACKOFF_MULTIPLIER	2.0	用于增加退避时间的乘数
MCP 服务器配置
SPL_MCPS_0_ID	""	第一个 MCP 服务器的标识符
SPL_MCPS_0_COMMAND	""	要为第一个服务器执行的命令
SPL_MCPS_0_ARGS	""	作为空格分隔字符串的命令参数
SPL_MCPS_0_ENV_*	""	服务器的环境变量（以 SPL_MCPS_0_ENV_ 为前缀）
SPL_MCPS_1_ID 等。	""	其他服务器的配置（递增索引）
MCP 重试配置
SPL_MSPS_RETRY_MAX_RETRIES	3	MCP 服务器连接的最大重试次数
SPL_MSPS_RETRY_INITIAL_BACKOFF	1.0	初始退避时间（秒）
SPL_MSPS_RETRY_MAX_BACKOFF	30.0	最大退避时间（秒）
SPL_MSPS_RETRY_BACKOFF_MULTIPLIER	2.0	用于增加退避时间的乘数
运行时配置
SPL_LOG_LEVEL	"info"	日志级别（debug、info、warn、error）
SPL_LOG_OUTPUT	"stderr"	日志输出目标（stdout、stderr、文件路径）
SPL_RUNTIME_STDIO_ENABLED	true	启用 stdin/stdout 传输
SPL_RUNTIME_STDIO_BUFFER_SIZE	8192	stdio 传输的缓冲区大小
SPL_RUNTIME_HTTP_ENABLED	false	启用 HTTP 传输
SPL_RUNTIME_HTTP_HOST	"localhost"	HTTP 服务器的主机
SPL_RUNTIME_HTTP_PORT	3000	HTTP 服务器的端口

有关配置选项的更多详细信息，请参阅 环境变量参考。

运行代理

守护程序模式 (HTTP 服务器)

./speelka-agent --daemon [--config config.yaml]

CLI 模式 (标准输入/输出)

./speelka-agent [--config config.yaml]

使用示例

HTTP API

在守护程序模式下运行时，代理公开 HTTP 端点：

# 向代理发送请求
curl -X POST http://localhost:3000/message -H "Content-Type: application/json" -d '{
  "method": "tools/call",
  "params": {
    "name": "process",
    "arguments": {
      "input": "你的查询内容"
    }
  }
}'

外部工具集成

在 YAML 配置文件中使用 MCP 协议连接到外部工具：

agent:
  # ... 其他代理配置 ...
  connections:
    mcpServers:
      # 用于 Playwright 浏览器自动化的 MCP 服务器
      playwright:
        command: "mcp-playwright"
        args: []

      # 用于文件系统操作的 MCP 服务器
      filesystem:
        command: "mcp-filesystem-server"
        args: ["."]

或者使用环境变量：

# 用于 Playwright 浏览器自动化的 MCP 服务器
export SPL_MCPS_0_ID="playwright"
export SPL_MCPS_0_COMMAND="mcp-playwright"
export SPL_MCPS_0_ARGS=""

# 用于文件系统操作的 MCP 服务器
export SPL_MCPS_1_ID="filesystem"
export SPL_MCPS_1_COMMAND="mcp-filesystem-server"
export SPL_MCPS_1_ARGS="."

支持的 LLM 提供商

• OpenAI: GPT-3.5, GPT-4, GPT-4o
• Anthropic: Claude 模型

文档

有关更多详细信息，请参阅：

• 系统架构
• 实现细节
• 项目文件结构
• 参考资料
• 外部资源

开发

运行测试

go test ./...

辅助命令

run 脚本提供了用于常见操作的命令：

# 开发
./run build        # 构建项目
./run test         # 运行带有覆盖率的测试
./run check        # 运行所有检查
./run lint         # 运行 linter

# 交互
./run call         # 使用简单查询进行测试
./run call-multistep # 使用多步骤查询进行测试
./run call-news    # 测试新闻代理
./run fetch_url    # 使用 MCP 获取 URL

# 检查
./run inspect      # 使用 MCP 检查器运行

有关更多选项，请参阅 命令参考。

许可证

MIT 许可证