克劳德代理代理

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

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

1. --allowedTools 标志(必需)

-p模式下的Claude CLI限制文件操作。您必须添加:如果没有此内容,代理将报告写入/编辑操作的“权限被拒绝”。

2.SSE流媒体格式(必填)

Agentica 期望 SSE 流式传输,而不是纯 JSON:

3. REPL 响应格式(必需)

代理必须将结果作为带有 return 语句的 Python 代码块返回:Agentica 的 REPL 解析器在 ```python and ``` 之间提取代码。

抗幻觉提示工程

除非您明确警告他们,否则代理会在不实际使用工具的情况下产生成功的幻觉:

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@parcadei · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
允许外网请求
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Agentica-Claude Code Proxy Integration

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

## 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

## Architecture Overview

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

## Critical Requirements

### 1. --allowedTools Flag (REQUIRED)

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.

### 2. SSE Streaming Format (REQUIRED)

Agentica expects SSE streaming, not plain JSON:

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

### 3. REPL Response Format (REQUIRED)

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 \`\`\`.

## Anti-Hallucination Prompt Engineering

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

```
## 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.
```

## 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/`

## Debugging

### Check Agent Logs

```bash
cat logs/agent-<N>.log
```

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

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

### Verify File Operations

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

## Server Commands

### Start Servers

```bash
# 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
```

### Use Swarm

```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
```

## 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`

## 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 |

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。