agentica-claude-proxy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agentica-Claude Code Proxy Integration

Agentica-Claude Code 代理集成

Use this skill when developing or debugging the Agentica-Claude proxy integration.

在开发或调试Agentica-Claude代理集成时使用本技能。

When to Use

使用场景

Setting up Agentica agents to use Claude Code tools
Debugging agent hallucination issues
Fixing permission errors in file operations
Understanding the REPL response format

配置Agentica Agent以使用Claude Code工具
调试智能体幻觉问题
修复文件操作中的权限错误
理解REPL响应格式

Architecture Overview

架构概述

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

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

Critical Requirements

关键要求

1. --allowedTools Flag (REQUIRED)

1. --allowedTools 参数（必填）

Claude CLI in

-p

mode restricts file operations. You MUST add:

python

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

Without this, agents will report "permission denied" for Write/Edit operations.

处于

-p

模式的Claude CLI会限制文件操作。你必须添加：

python

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

如果不添加，智能体在执行Write/Edit操作时会提示“permission denied”。

2. SSE Streaming Format (REQUIRED)

2. SSE流式格式（必填）

Agentica expects SSE streaming, not plain JSON:

python

undefined

Agentica期望SSE流式响应，而非纯JSON：

python

undefined

Response format

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

undefined

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

undefined

3. REPL Response Format (REQUIRED)

3. REPL响应格式（必填）

Agents MUST return results as Python code blocks with a return statement:

python

return "your result here"

Agentica's REPL parser extracts code between ```python and ```.

智能体必须以包含return语句的Python代码块形式返回结果：

python

return "your result here"

Agentica的REPL解析器会提取```python和```之间的代码。

Anti-Hallucination Prompt Engineering

防幻觉提示词工程

Agents will hallucinate success without actually using tools unless you explicitly warn them:

undefined

除非明确警告，否则智能体可能会在未实际使用工具的情况下虚构成功结果：

undefined

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:

FIRST: Actually invoke the tool (Read, Write, Edit, or Bash)
SECOND: Wait for the tool result
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.

undefined

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:

FIRST: Actually invoke the tool (Read, Write, Edit, or Bash)
SECOND: Wait for the tool result
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.

undefined

Path Sandboxing

路径沙箱限制

Both Claude Code and Agentica have sandboxes:

```
/tmp/
```
paths are blocked by Claude Code
Files outside project directory blocked by Agentica

Solution: Use project-relative paths like

workspace/

instead of

/tmp/

Claude Code和Agentica均设有沙箱限制：

Claude Code会阻止
```
/tmp/
```
路径
Agentica会阻止项目目录外的文件

解决方案： 使用项目相对路径，如

workspace/

，而非

/tmp/

Debugging

调试方法

Check Agent Logs

查看Agent日志

bash

cat logs/agent-<N>.log

Note: Logs only show final conversational response, not tool invocations.

bash

cat logs/agent-<N>.log

注意：日志仅显示最终对话响应，不包含工具调用记录。

Test Proxy Directly

直接测试代理

bash

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}'

bash

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}'

Verify File Operations

验证文件操作

bash

undefined

bash

undefined

After agent claims to create file

ls -la workspace/test.txt cat workspace/test.txt

undefined

ls -la workspace/test.txt cat workspace/test.txt

undefined

Server Commands

服务器命令

Start Servers

启动服务器

bash

undefined

bash

undefined

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

undefined

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

undefined

Use Swarm

使用Swarm

bash

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

bash

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

Health Checks

健康检查

bash

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

bash

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

Reference Files

参考文件

Proxy implementation:
```
scripts/agentica/claude_proxy.py
```
REPL_BASELINE prompt:
```
scripts/agentica/claude_proxy.py:49-155
```
Comprehensive test:
```
workspace/test_swarm_all_tools.py
```
DependencySwarm:
```
scripts/agentica/dependency_swarm.py
```

代理实现：
```
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
```

Common Errors

常见错误

Error	Cause	Fix
"Permission denied"	Missing --allowedTools	Add `--allowedTools Read Write Edit Bash`
Agent claims success but file not created	Hallucination	Add anti-hallucination prompt section
"Cannot access /tmp/..."	Sandbox restriction	Use project-relative paths
"APIConnectionError"	Wrong response format	Use SSE streaming (data: {...}\n\n)
"NameError: view_file"	Agent using REPL functions	Add REPL_BASELINE with native tool examples

错误	原因	修复方案
"Permission denied"	缺少--allowedTools参数	添加 `--allowedTools Read Write Edit Bash`
智能体声称操作成功但未创建文件	幻觉问题	添加防幻觉提示词段落
"Cannot access /tmp/..."	沙箱限制	使用项目相对路径
"APIConnectionError"	响应格式错误	使用SSE流式格式（data: {...}\n\n）
"NameError: view_file"	智能体使用了REPL函数	添加包含原生工具示例的REPL_BASELINE