Speelka Agent

Speelka Agent

Model Context Protocol (MCP) に基づいたユニバーサル LLM エージェント。外部ツール、柔軟な設定、拡張可能なロギングをサポートしています。

主な機能

• マルチエージェントオーケストレーション: 他の MCP サーバーのツールをサポートします。
• 柔軟な設定: YAML、JSON、環境変数、オーバーレイ、プロパティベースオーバーレイ。
• 拡張可能なロギング: 一元化された LogConfig、stdout、stderr、ファイル、MCP プロトコル、カスタム/json/text フォーマットへの出力。
• セキュリティ: キー分離、ログ保護、ツールアクセス制御。
• テスト: ゴールデンシリアライゼーションテスト、プロパティベースオーバーレイ、ユニット/インテグレーション/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 ログはプロトコル経由で利用可能、または stdio サーバーの場合は stderr にフォールバックします。
• フォーマット: カスタム、json、text、不明。
• 詳細は documents/architecture.md と documents/implementation.md を参照してください。

テスト

• ユニット、インテグレーション、E2E。
• プロパティベースオーバーレイテスト (エッジケース、マップマージ、ゼロ値保持)。
• テスト例: documents/implementation.md。

プロジェクト構成

• 詳細は documents/file_structure.md を参照してください。
• 主要ディレクトリ: internal/agent、internal/logger、internal/mcp_connector、internal/types。

クイックスタート

1. リポジトリをクローンしてエージェントをビルドします:

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

2. 設定を準備します (上記の例を参照) または環境変数 (SPL_...) を使用します。
3. エージェントを実行します:
   • 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 サーバーの応答を拡張、絞込、または変更します。
• 「実際の」ツール実装と LLM ベースのツール実装の間で簡単に切り替えます。
• MCP サーバーで利用可能なツールを制限することで機能を制限します。
• 単一セッション内で複数の MCP ツールにまたがるマルチステップワークフローをオーケストレーションします。
• リクエストごとのトークンとコスト予算を強制して予測可能な使用を実現します。
• LLM または MCP サーバーの一時的なエラーに対する自動再試行と指数バックオフ。
• 統一された設定経由で LLM サービス (OpenAI、Anthropic) 間のシームレスなプロバイダ切り替え。

主な機能

• 正確なエージェント定義: プロンプトエンジニアリングを通じてエージェントの動作を定義
• クライアント側コンテキスト最適化: コンテキストサイズを削減し、効率的なトークン使用を実現
• LLM の柔軟性: クライアント側とエージェント側で異なる LLM プロバイダーを使用可能
• 一元化されたツール管理: すべてのツールを一つのコントロールポイントで管理
• 複数の統合オプション: MCP stdio、MCP HTTP、シンプル HTTP API
• 組み込みの信頼性: 一時的な障害に対するリトライメカニズム
• 拡張性: クライアント側の変更なしでシステム動作を拡張可能
• MCP 対応ログ記録: MCP 通知を備えた構造化ログ
• トークン管理: 自動トークンカウント
• 柔軟な設定: 環境変数、YAML、JSON に対応
• LLMService.SendRequest は LLMResponse 構造体を返します:
  • レスポンステキスト
  • ツール呼び出しのリスト
  • CompletionTokens、PromptTokens、ReasoningTokens、TotalTokens (トークン使用量)
• インターフェース: SendRequest(ctx, messages, tools) (LLMResponse, error)

はじめに

前提条件

• 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/minimal.yaml: 基本的なエージェント設定 (YAML)
• site/examples/ai-news.yaml: AI ニュースエージェント設定 (YAML)
• site/examples/architect.yaml: アーキテクトエージェント設定 (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_ というプレフィックスが付きます:

環境変数	デフォルト値	説明
エージェント設定
SPL_AGENT_NAME	必須	エージェントの名前
SPL_AGENT_VERSION	"1.0.0"	エージェントのバージョン
ツール設定
SPL_AGENT_TOOL_NAME	必須	エージェントが提供するツールの名前
SPL_AGENT_TOOL_DESCRIPTION	必須	ツール機能の説明
SPL_AGENT_TOOL_ARGUMENT_NAME	必須	ツールの引数の名前
SPL_AGENT_TOOL_ARGUMENT_DESCRIPTION	必須	ツールの引数の説明
LLM 設定
SPL_AGENT_LLM_PROVIDER	必須	LLM サービスのプロバイダー（例："openai"、"anthropic"）
SPL_AGENT_LLM_APIKEY	必須	LLM プロバイダーの API キー
SPL_AGENT_LLM_MODEL	必須	モデル名（例："gpt-4o"、"claude-3-opus-20240229"）
SPL_AGENT_LLM_MAX_TOKENS	0	生成するトークンの最大数（0 は無制限を意味します）
SPL_AGENT_LLM_TEMPERATURE	0.7	生成時のランダム性を制御するテンパラチャーパラメータ
SPL_AGENT_LLM_PROMPTTEMPLATE	必須	システムプロンプトのテンプレート（SPL_AGENT_TOOL_ARGUMENTNAME の値と {{tools}} に対応するプレースホルダーを含める必要があります）
チャット設定
SPL_AGENT_CHAT_MAX_LLM_ITERATIONS	100	LLM 反復処理の最大数
SPL_AGENT_CHAT_MAX_TOKENS	0	チャット履歴の最大トークン数（0 はモデルに基づきます）
SPL_AGENT_CHAT_REQUEST_BUDGET	1.0	リクエストあたりの最大コスト（USD またはトークン相当）（0 = 無制限）
LLM リトライ設定
SPL_AGENT_LLM_RETRY_MAX_RETRIES	3	LLM 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 サーバーのポート
詳細については、環境変数リファレンスを参照してください。

エージェントの実行

デーモンモード（HTTP サーバー）

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

CLI モード（標準入出力）

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

使用例

HTTP API

デーモンモードで実行する場合、エージェントは 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"
    }
  }
}'

外部ツール統合

YAML 設定で MCP プロトコルを使用して外部ツールに接続します：

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="."

サポートされている LLM プロバイダー

• 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

ダイレクトコールモード

エージェントをダイレクトコールモードで実行して、単一のクエリを処理し、JSON 結果を出力できます。これはスクリプト作成、自動化、または他のツールとの統合に便利です。

例：

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

• エージェントはクエリを処理し、単一の JSON 結果を標準出力に出力します。
• すべてのログとデバッグ出力は標準エラーに送信されます。
• 出力 JSON は常に以下のフィールドを含みます：success、result、meta、error。

ヒント：

• このモードをスクリプト内で使用し、出力を jq または他のツールにパイプして、さらに処理することができます。