🚀 《Speelka Agent》使用文档

《Speelka Agent》是一款用于特定场景的代理工具，通过简单配置即可快速运行，支持多种模式和配置方式，为用户提供便捷的代理服务。

🚀 快速开始

📦 安装指南

使用以下命令安装最新版本的speelka-agent：

go install github.com/speelka/speelka-agent/cmd/speelka-agent@latest

⚙️ 创建配置文件

创建一个config.yaml文件，示例如下：

agent:
  id: "my-agent"         # 设置为唯一的标识符
  name: "My Agent"       # 设置为一个有意义的名字
  description: "A test agent for Speelka."   # 可选，描述你的代理
  version: "0.1"        # 可选，设置版本号

  # 配置MCP服务器连接
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]

▶️ 运行代理

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

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

CLI模式（标准输入/输出）

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

📚 详细文档

🔧 环境变量配置

以下是通过环境变量配置代理的示例：

# 设置代理的基本信息
export SPL_AGENT_ID="my-agent"
export SPL_AGENT_NAME="My Agent"

# 配置MCP服务器连接
export SPL_MCPS_0_ID="time"
export SPL_MCPS_0_COMMAND="docker"
export SPL_MCPS_0_ARGS="run -i --rm mcp/time"

export SPL_MCPS_1_ID="filesystem"
export SPL_MCPS_1_COMMAND="mcp-filesystem-server"
export SPL_MCPS_1_ARGS="/path/to/directory"

📄 YAML配置文件参考

以下是config.yaml文件的完整参考：

agent:
  id: string         # 必填，代理的唯一标识符
  name: string       # 必填，代理的名字
  description: string   # 可选，代理的描述
  version: string    # 可选，代理的版本号

  # 配置MCP服务器连接
  connections:
    mcpServers:
      <server_id>:
        command: string          # 必填，启动MCP服务器的命令
        args: list of strings    # 可选，传递给命令的参数
        includeTools: list of strings   # 可选，包含工具列表，只有这些工具会被导出
        excludeTools: list of strings   # 可选，排除的工具列表

# 运行时配置
runtime:
  logLevel: string      # 可选，默认为"info"
  logOutput: string     # 可选，默认为"stderr"
  stdioEnabled: boolean  # 可选，默认为true
  stdioBufferSize: int   # 可选，默认为8192
  httpEnabled: boolean    # 可选，默认为false
  httpHost: string       # 可选，默认为"localhost"
  httpPort: int          # 可选，默认为3000

# 支持的LLM提供程序
llmProviders:
  openai:
    enabled: boolean     # 可选，默认为true
    apiKey: string        # 必填，OpenAI API密钥
    model: string         # 可选，默认为"gpt-3.5-turbo"
  anthropic:
    enabled: boolean      # 可选，默认为true
    apiKey: string         # 必填，Anthropic API密钥
    model: string          # 可选，默认为"claude-2"

🔍 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

💻 使用示例

🌟 基础用法

创建自定义代理

./speelka-agent create custom-agent --config config.yaml

运行代理

运行名为custom-agent的代理：

./speelka-agent run custom-agent --config config.yaml