Speelka Agent

Speelka Agent

基于 Model Context Protocol（MCP）的通用大模型 Agent，支持外部工具、灵活配置和可扩展日志。

主要功能

• 多 Agent 编排：支持来自其他 MCP 服务的工具。
• 灵活配置：YAML、JSON、环境变量、叠加层和基于属性的叠加层。
• 可扩展日志：集中式 LogConfig、输出到 stdout、stderr、文件、MCP 协议、自定义 / JSON / 文本格式。
• 安全性：密钥隔离、日志保护、工具访问控制。
• 测试：黄金序列化测试、基于属性的叠加层、单元 / 集成 / E2E。
• 可扩展性：HTTP 和 stdio 支持、动态工具 / 会话管理。

架构

• 所有组件都是接口驱动的、经过测试的，并遵循单一职责原则。
• 详见 documents/architecture.md。

示例配置（YAML）

runtime:
  log:
    defaultLevel: info
    output: ':mcp:'
    format: json
  transports:
    stdio:
      enabled: true
      buffer_size: 1024
    http:
      enabled: false
      host: localhost
      port: 3000
agent:
  name: "speelka-agent"
  version: "v1.0.0"
  tool:
    name: "process"
    description: "Process tool for user queries"
    argument_name: "input"
    argument_description: "User query"
  chat:
    max_tokens: 0
    max_llm_iterations: 25
    request_budget: 0.0
  llm:
    provider: "openai"
    apiKey: "dummy-api-key"
    model: "gpt-4o"
    temperature: 0.7
    promptTemplate: "You are a helpful assistant. {{input}}. Available tools: {{tools}}"
    retry:
      max_retries: 3
      initial_backoff: 1.0
      max_backoff: 30.0
      backoff_multiplier: 2.0
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
        timeout: 10
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]
    retry:
      max_retries: 2
      initial_backoff: 1.5
      max_backoff: 10.0
      backoff_multiplier: 2.5

日志

• 通过 LogConfig 管理：级别、格式、输出（stdout、stderr、文件、MCP）。
• MCP 日志可通过协议获取，或回退到 stderr（针对 stdio 服务）。
• 格式：自定义、json、text、unknown。
• 详见 documents/architecture.md 和 documents/implementation.md。

测试

• 单元、集成、E2E。
• 基于属性的叠加层测试（边界情况、映射合并、零值保留）。
• 测试示例：documents/implementation.md。

项目结构

• 详见 documents/file_structure.md。
• 关键目录：internal/agent、internal/logger、internal/mcp_connector、internal/types。

快速开始

1. 克隆仓库并构建 Agent：

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

2. 准备配置（见上面示例）或使用环境变量（SPL_...）。
3. 运行 Agent：
   • HTTP 模式：./speelka-agent --daemon [--config config.yaml]
   • CLI/stdio：./speelka-agent [--config config.yaml]

文档

• 架构：documents/architecture.md
• 实现与测试：documents/implementation.md
• 文件结构：documents/file_structure.md
• 外部资源：documents/remote_resources.md

---

关于叠加层、MCP 日志、测试和结构的详细信息，请参阅 documents/ 文件夹中的文档。

flowchart TB
    User["Any MCP Client"] --> |"1.Request"| Agent["Speelka Agent"]
    Agent --> |"2.Format prompt"| LLM["LLM Service"]
    LLM --> |"3.Tool calls"| Agent
    Agent --> |"4.Execute tools"| Tools["External MCP Tools"]
    Tools --> |"5.Return results"| Agent
    Agent --> |"6.Process repeat"| LLM
    Agent --> |"7.Final answer"| User

使用场景

• 通过将大型复杂指令分解为专门化、精细化的任务来提高准确性。
• 通过为不同的任务部分使用不同的大模型来降低成本。
• 扩展、限制或修改第三方 MCP 服务响应。
• 在"真实"和基于大模型的工具实现之间轻松切换。
• 通过限制 MCP 服务中可用的工具来限制功能。
• 在单个会话中跨多个 MCP 工具编排多步工作流。
• 对每个请求强制执行 token 和成本预算，以实现可预测的使用。
• 针对瞬间大模型或 MCP 服务错误的自动重试和指数退避。
• 通过统一配置在大模型服务提供商（OpenAI、Anthropic）之间无缝切换。

主要功能

• 精确 Agent 定义：通过提示词工程定义 Agent 行为
• 客户端上下文优化：减少上下文大小以实现高效的 token 使用
• 大模型灵活性：在客户端和 Agent 端使用不同的大模型提供商
• 集中式工具管理：所有工具的单一控制点
• 多种集成选项：MCP stdio、MCP HTTP、Simple HTTP API
• 内置可靠性：用于暂时性故障的重试机制
• 可扩展性：无需客户端更改即可扩展系统行为
• MCP 感知日志：带有 MCP 通知的结构化日志
• Token 管理：自动 token 计数
• 灵活配置：环境变量、YAML、JSON
• LLMService.SendRequest 返回 LLMResponse 结构体，包含：
  • 响应文本
  • 工具调用列表
  • CompletionTokens、PromptTokens、ReasoningTokens、TotalTokens（token 用量）
• 接口：SendRequest(ctx, messages, tools) (LLMResponse, error)

快速开始

前置要求

• Go 1.19 或更高版本
• 大模型 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/minimal.yaml：基础 Agent 配置 (YAML)
• site/examples/ai-news.yaml：AI 新闻 Agent 配置 (YAML)
• site/examples/architect.yaml：架构师 Agent 配置 (YAML)

简单 YAML 配置示例：

agent:
  name: "simple-speelka-agent"
  version: "1.0.0"
  tool:
    name: "process"
    description: "Process tool for handling user queries with LLM"
    argument_name: "input"
    argument_description: "The user query to process"
  llm:
    provider: "openai"
    apiKey: ""  # Set via environment variable for security
    model: "gpt-4o"
    temperature: 0.7
    promptTemplate: "You are a helpful AI assistant. Respond to the following request: {{input}}. Provide a detailed and helpful response. Available tools: {{tools}}"
  chat:
    max_tokens: 0
    max_llm_iterations: 25
    request_budget: 0.0
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
        includeTools:
          - now
          - utc
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]
        excludeTools:
          - delete
runtime:
  log:
    level: "info"
  transports:
    stdio:
      enabled: true

使用环境变量

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

环境变量	默认值	描述
Agent 配置
SPL_AGENT_NAME	Required	Agent 的名称
SPL_AGENT_VERSION	"1.0.0"	Agent 的版本
工具配置
SPL_AGENT_TOOL_NAME	Required	Agent 提供的工具的名称
SPL_AGENT_TOOL_DESCRIPTION	Required	工具功能的描述
SPL_AGENT_TOOL_ARGUMENT_NAME	Required	工具参数的名称
SPL_AGENT_TOOL_ARGUMENT_DESCRIPTION	Required	工具参数的描述
大模型配置
SPL_AGENT_LLM_PROVIDER	Required	大模型服务提供商（例如 "openai"、"anthropic"）
SPL_AGENT_LLM_APIKEY	Required	大模型提供商的 API 密钥
SPL_AGENT_LLM_MODEL	Required	模型名称（例如 "gpt-4o"、"claude-3-opus-20240229"）
SPL_AGENT_LLM_MAX_TOKENS	0	最大生成令牌数（0 表示无限制）
SPL_AGENT_LLM_TEMPERATURE	0.7	生成随机性的温度参数
SPL_AGENT_LLM_PROMPTTEMPLATE	Required	系统提示词的模板（必须包含与 SPL_AGENT_TOOL_ARGUMENTNAME 值匹配的占位符和 {{tools}}）
聊天配置
SPL_AGENT_CHAT_MAX_LLM_ITERATIONS	100	大模型迭代的最大次数
SPL_AGENT_CHAT_MAX_TOKENS	0	聊天历史中的最大令牌数（0 表示基于模型）
SPL_AGENT_CHAT_REQUEST_BUDGET	1.0	每个请求的最大成本（美元或令牌等价值）（0 = 无限制）
大模型重试配置
SPL_AGENT_LLM_RETRY_MAX_RETRIES	3	大模型 API 调用的最大重试次数
SPL_AGENT_LLM_RETRY_INITIAL_BACKOFF	1.0	初始退避时间（秒）
SPL_AGENT_LLM_RETRY_MAX_BACKOFF	30.0	最大退避时间（秒）
SPL_AGENT_LLM_RETRY_BACKOFF_MULTIPLIER	2.0	增加退避时间的乘数
MCP 服务配置
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ID	""	第一个 MCP 服务的标识符
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_COMMAND	""	第一个服务要执行的命令
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ARGS	""	命令参数，以空格分隔的字符串形式
SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ENV_*	""	服务的环境变量（前缀为 SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ENV_）
SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ID 等	""	其他服务的配置（增加索引）
MCP 重试配置
SPL_AGENT_CONNECTIONS_RETRY_MAX_RETRIES	3	MCP 服务连接的最大重试次数
SPL_AGENT_CONNECTIONS_RETRY_INITIAL_BACKOFF	1.0	初始退避时间（秒）
SPL_AGENT_CONNECTIONS_RETRY_MAX_BACKOFF	30.0	最大退避时间（秒）
SPL_AGENT_CONNECTIONS_RETRY_BACKOFF_MULTIPLIER	2.0	增加退避时间的乘数
运行时配置
SPL_RUNTIME_LOG_DEFAULTLEVEL	"info"	日志默认级别（debug、info、warn、error）
SPL_RUNTIME_LOG_OUTPUT	":stderr:"	日志输出目标（:stdout:、:stderr:、:mcp:、文件路径）
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 服务器的端口
有关更多详情，请参阅环境变量参考。

运行 Agent

守护进程模式（HTTP 服务器）

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

命令行模式（标准输入/输出）

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

使用示例

HTTP API

在守护进程模式下运行时，Agent 暴露 HTTP 端点：

# Send a request to the agent
curl -X POST http://localhost:3000/message -H "Content-Type: application/json" -d '{
  "method": "tools/call",
  "params": {
    "name": "process",
    "arguments": {
      "input": "Your query here"
    }
  }
}'

外部工具集成

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

agent:
  # ... other agent configuration ...
  connections:
    mcpServers:
      # MCP server for Playwright browser automation
      playwright:
        command: "mcp-playwright"
        args: []

      # MCP server for filesystem operations
      filesystem:
        command: "mcp-filesystem-server"
        args: ["."]

或使用环境变量：

# MCP server for Playwright browser automation
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ID="playwright"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_COMMAND="mcp-playwright"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_0_ARGS=""

# MCP server for filesystem operations
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ID="filesystem"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_COMMAND="mcp-filesystem-server"
export SPL_AGENT_CONNECTIONS_MCPSERVERS_1_ARGS="."

支持的大模型提供商

• OpenAI：GPT-3.5、GPT-4、GPT-4o
• Anthropic：Claude 模型

文档

有关更多详情，请参阅：

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

开发

运行测试

go test ./...

辅助命令

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

# Development
./run build        # Build the project
./run test         # Run tests with coverage
./run check        # Run all checks
./run lint         # Run linter

# Interaction
./run call         # Test with simple query
./run call-multistep # Test with multi-step query
./run call-news    # Test news agent
./run fetch_url    # Fetch a URL using MCP

# Inspection
./run inspect      # Run with MCP inspector

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

许可证

MIT 许可证

MCP 服务工具筛选

您可以使用 mcpServers 部分中的以下选项来控制从每个 MCP 服务导出哪些工具：

• includeTools：（可选）要包含的工具名称列表。只有这些工具才能从服务中使用。
• excludeTools：（可选）要排除的工具名称列表。这些工具不会从服务中提供。
• 如果两者都设置，先应用 includeTools，然后应用 excludeTools。
• 工具名称区分大小写。

示例：

connections:
  mcpServers:
    time:
      command: "docker"
      args: ["run", "-i", "--rm", "mcp/time"]
      includeTools:
        - now
        - utc
    filesystem:
      command: "mcp-filesystem-server"
      args: ["/path/to/directory"]
      excludeTools:
        - delete

直接调用模式

您可以在直接调用模式下运行 Agent 来处理单个查询并输出 JSON 结果。这对脚本编写、自动化或与其他工具集成很有用。

示例：

./bin/speelka-agent --config site/examples/minimal.yaml --call 'What is 2+2?'

• Agent 将处理查询并向标准输出打印单个 JSON 结果。
• 所有日志和调试输出都发送到标准错误。
• 输出 JSON 将始终包含以下字段：success、result、meta 和 error。

提示：

• 您可以在脚本中使用此模式，并将输出管道传递到 jq 或其他工具进行进一步处理。