agentica-server

Agentica サーバー + Claude プロキシのセットアップ

ローカルの Claude プロキシで Agentica SDK を実行するための完全なリファレンスです。これにより、Python エージェントは推論バックエンドとして Claude CLI を使用できます。

使用する場面

以下の場合に、このスキルを使用します。

• Claude プロキシを使用した Agentica の開発を始める
• SDK、サーバー、プロキシ間の接続問題をデバッグする
• 新しい Agentica 環境をセットアップする
• エージェントのツールアクセスやハルシネーションの問題をトラブルシューティングする

アーキテクチャ

Agentica SDK (client code)
    | S_M_BASE_URL=http://localhost:2345
    v
ClientSessionManager
    |
    v
Agentica Server (agentica-server)
    | INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions
    v
Claude Proxy (claude_proxy.py)
    |
    v
Claude CLI (claude -p)

環境変数

変数	設定者	使用者	用途
INFERENCE_ENDPOINT_URL	人間	agentica-server	サーバーが LLM 推論リクエストを送信する先
S_M_BASE_URL	人間	Agentica SDK クライアント	SDK がセッションマネージャーに接続する先

重要： これらは同じエンドポイントではありません！

• SDK はサーバーに接続します（ポート 2345）
• サーバーはプロキシに接続します（ポート 8080）

起動順序

次の順序で起動する必要があります（それぞれ別のターミナルで実行します）。

ターミナル 1：Claude プロキシ

uv run python scripts/agentica/claude_proxy.py --port 8080

ターミナル 2：Agentica サーバー

必ず専用のディレクトリから実行してください。

cd workspace/agentica-research/agentica-server
INFERENCE_ENDPOINT_URL=http://localhost:8080/v1/chat/completions uv run agentica-server --port 2345

ターミナル 3：エージェントスクリプト

S_M_BASE_URL=http://localhost:2345 uv run python scripts/agentica/your_script.py

ヘルスチェック

# Claude proxy health
curl http://localhost:8080/health

# Agentica server health
curl http://localhost:2345/health

よくあるエラーと解決方法

1. エージェントの起動後に発生する APIConnectionError

症状： エージェントの起動には成功しますが、最初の呼び出しで接続エラーが発生します。

原因： Claude プロキシが SSE 形式ではなく、通常の JSON を返しています。

解決方法： プロキシは Server-Sent Events 形式を返す必要があります。

data: {"choices": [...]}\n\n

2. agentica-server の ModuleNotFoundError

症状： ModuleNotFoundError: No module named 'agentica_server'

原因： 間違ったディレクトリから uv run agentica-server を実行しています。

解決方法： まず cd workspace/agentica-research/agentica-server を実行する必要があります。

3. エージェントが Read/Write/Edit ツールを使用できない

症状： エージェントがファイルを読み取らずに、ファイルの内容を尋ねます。

原因： claude_proxy.py の CLI 呼び出しに --allowedTools がありません。

解決方法： プロキシでツールの権限を渡す必要があります。

claude -p ... --allowedTools Read Write Edit Bash

4. エージェントがタスクを完了していないのに成功したと主張する

症状： エージェントが「ファイルを作成しました」と言いますが、ファイルが存在しません。

原因： ハルシネーションです。エージェントが実行せずに、実行するつもりの操作を説明しています。

解決方法： REPL_BASELINE に、ハルシネーションを強く防止するプロンプトを追加しました。

CRITICAL: Use ACTUAL tools. Never DESCRIBE using tools.

5. agent.call() のタイムアウト

症状： 呼び出しが 30 秒以上ハングした後、タイムアウトします。

原因： Claude CLI の処理が長引いているか、ループから抜け出せなくなっています。

解決方法： プロキシのログで実際の CLI 出力を確認してください。プロンプトを簡略化する必要がある場合があります。

主要なファイル

ファイル	用途
scripts/agentica/claude_proxy.py	SSE ストリーミングに対応した OpenAI 互換プロキシ
workspace/agentica-research/agentica-server/	ローカルの agentica-server インストール先
scripts/agentica/PATTERNS.md	マルチエージェントパターンのドキュメント

簡単な動作確認

スタック全体をテストします。

# 1. Verify proxy responds
curl http://localhost:8080/health

# 2. Verify server responds
curl http://localhost:2345/health

# 3. Test inference through proxy
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude","messages":[{"role":"user","content":"Say hello"}]}'

チェックリスト

エージェントを実行する前に、以下を確認してください。

• Claude プロキシがポート 8080 で実行中
• Agentica サーバーがポート 2345 で実行中（専用のディレクトリから起動）
• クライアントスクリプト用に S_M_BASE_URL が設定済み
• サーバー用に INFERENCE_ENDPOINT_URL が設定済み
• どちらのヘルスチェックも 200 を返す