agentica-claude-proxy

Agentica-Claude Code プロキシ統合

Agentica-Claude プロキシ統合の開発またはデバッグを行う際に、このスキルを使用してください。

使用する場面

• Claude Code ツールを使用するよう Agentica エージェントを設定するとき
• エージェントの幻覚に関する問題をデバッグするとき
• ファイル操作の権限エラーを修正するとき
• REPL の応答形式を確認するとき

アーキテクチャの概要

Agentica Agent → S_M_BASE_URL → Claude Proxy → claude -p → Claude CLI (with tools)
                 (localhost:2345)   (localhost:8080)

必須要件

1. --allowedTools フラグ（必須）

-p モードの Claude CLI では、ファイル操作が制限されます。必ず次を追加してください。

subprocess.run([
    "claude", "-p", prompt,
    "--append-system-prompt", system_prompt,
    "--allowedTools", "Read", "Write", "Edit", "Bash",  # REQUIRED
])

これがないと、エージェントは Write/Edit 操作で「permission denied」と報告します。

2. SSE ストリーミング形式（必須）

Agentica が必要とするのは、通常の JSON ではなく SSE ストリーミングです。

# Response format
yield f"data: {json.dumps(chunk)}\n\n"
yield "data: [DONE]\n\n"

3. REPL 応答形式（必須）

エージェントは、return 文を含む Python コードブロックとして結果を返す必要があります。

return "your result here"

Agentica の REPL パーサーは、```python と ``` の間のコードを抽出します。

幻覚を防ぐプロンプトエンジニアリング

明示的に警告しないと、エージェントは実際にはツールを使用していないのに、成功したと幻覚することがあります。

## ANTI-HALLUCINATION WARNING

**STOP AND READ THIS CAREFULLY:**

You have access to these tools: Read, Write, Edit, Bash

When the task asks you to create/modify/run something:
1. FIRST: Actually invoke the tool (Read, Write, Edit, or Bash)
2. SECOND: Wait for the tool result
3. THIRD: Then return your answer based on what actually happened

**DO NOT** skip the tool invocation and just claim success!

If you didn't invoke a tool, you CANNOT claim the action succeeded.

パスのサンドボックス化

Claude Code と Agentica の両方にサンドボックスがあります。

• /tmp/ のパスは Claude Code によってブロックされます
• プロジェクトディレクトリ外のファイルは Agentica によってブロックされます

解決策： /tmp/ の代わりに workspace/ のようなプロジェクト相対パスを使用してください。

デバッグ

エージェントのログを確認する

cat logs/agent-<N>.log

注：ログに表示されるのは最終的な会話の応答のみで、ツールの呼び出しは表示されません。

プロキシを直接テストする

curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "claude", "messages": [{"role": "user", "content": "Create file at workspace/test.txt"}], "stream": false}'

ファイル操作を検証する

# After agent claims to create file
ls -la workspace/test.txt
cat workspace/test.txt

サーバーコマンド

サーバーを起動する

# Terminal 1: Proxy
uv run python scripts/agentica/claude_proxy.py --port 8080

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

Swarm を使用する

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

ヘルスチェック

curl http://localhost:8080/health  # Proxy
curl http://localhost:2345/health  # Agentica

参照ファイル

• プロキシの実装：scripts/agentica/claude_proxy.py
• REPL_BASELINE プロンプト：scripts/agentica/claude_proxy.py:49-155
• 包括的なテスト：workspace/test_swarm_all_tools.py
• DependencySwarm：scripts/agentica/dependency_swarm.py

よくあるエラー

エラー	原因	修正方法
"Permission denied"	--allowedTools が不足しています	--allowedTools Read Write Edit Bash を追加します
エージェントは成功したと主張するが、ファイルが作成されない	幻覚	幻覚を防ぐプロンプトのセクションを追加します
"Cannot access /tmp/..."	サンドボックスによる制限	プロジェクト相対パスを使用します
"APIConnectionError"	応答形式が正しくありません	SSE ストリーミング（data: {...}\n\n）を使用します
"NameError: view_file"	エージェントが REPL 関数を使用しています	ネイティブツールの使用例を含む REPL_BASELINE を追加します