Speelka Agent

🚀 Speelka Agent

Speelka Agent is a tool that allows you to create and run agents with specific configurations, facilitating interaction with MCP servers and LLM providers.

🚀 Quick Start

📦 Installation

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

📄 Create a Configuration File

Create a config.yaml file as follows:

agent:
  id: "my-agent"         # Set to a unique identifier
  name: "My Agent"       # Set to a meaningful name
  description: "A test agent for Speelka."   # Optional, describe your agent
  version: "0.1"        # Optional, set the version number

  # Configure MCP server connections
  connections:
    mcpServers:
      time:
        command: "docker"
        args: ["run", "-i", "--rm", "mcp/time"]
      filesystem:
        command: "mcp-filesystem-server"
        args: ["/path/to/directory"]

🚀 Run the Agent

Daemon Mode (HTTP Server)

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

CLI Mode (Standard Input/Output)

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

📚 Documentation

🌐 Environment Variable Configuration

The following is an example of configuring the agent via environment variables:

# Set basic information for the agent
export SPL_AGENT_ID="my-agent"
export SPL_AGENT_NAME="My Agent"

# Configure MCP server connections
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 Configuration File Reference

The following is a complete reference for the config.yaml file:

agent:
  id: string         # Required, unique identifier for the agent
  name: string       # Required, name of the agent
  description: string   # Optional, description of the agent
  version: string    # Optional, version number of the agent

  # Configure MCP server connections
  connections:
    mcpServers:
      <server_id>:
        command: string          # Required, command to start the MCP server
        args: list of strings    # Optional, arguments passed to the command
        includeTools: list of strings   # Optional, list of tools to include, only these tools will be exported
        excludeTools: list of strings   # Optional, list of tools to exclude

# Runtime configuration
runtime:
  logLevel: string      # Optional, default is "info"
  logOutput: string     # Optional, default is "stderr"
  stdioEnabled: boolean  # Optional, default is true
  stdioBufferSize: int   # Optional, default is 8192
  httpEnabled: boolean    # Optional, default is false
  httpHost: string       # Optional, default is "localhost"
  httpPort: int          # Optional, default is 3000

# Supported LLM providers
llmProviders:
  openai:
    enabled: boolean     # Optional, default is true
    apiKey: string        # Required, OpenAI API key
    model: string         # Optional, default is "gpt-3.5-turbo"
  anthropic:
    enabled: boolean      # Optional, default is true
    apiKey: string         # Required, Anthropic API key
    model: string          # Optional, default is "claude-2"

🛠️ MCP Server Tool Filtering

You can use the following options in the mcpServers section to control the tools exported by each MCP server:

• includeTools: (Optional) Specify a list of tool names to include. Only these tools will be exported from the server.
• excludeTools: (Optional) Specify a list of tool names to exclude. These tools will not be exported from the server.
• If both options are set, includeTools is applied first, followed by excludeTools.
• Tool names are case-sensitive.

Example:

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

💻 Usage Examples

🛠️ Create a Custom Agent

Create a custom agent:

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

🚀 Run the Agent

Run the agent named custom-agent:

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