# cagent

**Repository Path**: tinytaro/cagent

## Basic Information

- **Project Name**: cagent
- **Description**: 使用C语言实现通用Agent
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cagent — C 语言 LLM Agent

一个用纯 C 实现的通用 LLM Agent，仅依赖 **libcurl**（HTTP 通信）和 **cJSON**（JSON 解析）。对接 OpenAI 兼容 Chat Completions API，支持多轮对话、Tool/Function Calling、SSE 流式输出和对话持久化。

## 功能特性

- **OpenAI 兼容**：可直连 OpenAI / DeepSeek / Qwen / Kimi / Moonshot 等主流模型服务
- **多轮对话**：维护完整消息历史，支持连续上下文
- **Tool/Function Calling**：Agent 能自主调用工具完成任务，支持链式调用（单轮上限 10 次）
- **SSE 流式输出**：逐 token 实时打印响应，跨 chunk 边界正确解析
- **对话持久化**：自动保存到 `~/.cagent_history.json`，支持手动 save/load
- **内置工具**：`run_command` / `read_file` / `write_file` / `list_dir`
- **零运行时依赖**：除 libcurl + libcjson 外无任何第三方库

## 依赖

构建前需安装：

```bash
# Debian / Ubuntu
sudo apt-get install -y libcurl4-openssl-dev libcjson-dev pkg-config cmake gcc

# Fedora / RHEL
sudo dnf install -y libcurl-devel cjson-devel pkgconfig cmake gcc
```

| 依赖 | 最低版本 | 用途 |
|------|---------|------|
| CMake | 3.10 | 构建系统 |
| GCC / Clang | 支持 C11 | 编译器 |
| libcurl | 任意 | HTTP 客户端 |
| cJSON | 1.7+ | JSON 解析与构造 |
| pkg-config | 任意 | 定位 cJSON（推荐） |

## 构建

```bash
cd /home/taro/agent
mkdir -p build && cd build
cmake ..
cmake --build . -j
```

构建产物：`build/cagent`（约 46KB 可执行文件）。

安装到系统（可选）：

```bash
sudo cmake --install .
```

## 配置

通过环境变量配置，无需修改代码：

| 环境变量 | 必填 | 默认值 | 说明 |
|---------|------|--------|------|
| `OPENAI_API_KEY` | 是 | — | API 密钥 |
| `OPENAI_API_BASE` | 否 | `https://api.openai.com` | API 基础地址（无尾斜杠） |
| `OPENAI_MODEL` | 否 | `gpt-4o-mini` | 模型名 |
| `OPENAI_TEMPERATURE` | 否 | `0.7` | 采样温度 |
| `OPENAI_MAX_TOKENS` | 否 | 不限制 | 单次响应最大 token 数 |

### 对接常见服务

```bash
# OpenAI 官方
export OPENAI_API_KEY=sk-xxx
export OPENAI_MODEL=gpt-4o-mini

# DeepSeek
export OPENAI_API_KEY=sk-xxx
export OPENAI_API_BASE=https://api.deepseek.com
export OPENAI_MODEL=deepseek-chat          # 或 deepseek-reasoner

# 通义千问 (Qwen)
export OPENAI_API_KEY=sk-xxx
export OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
export OPENAI_MODEL=qwen-plus

# Kimi (Moonshot)
export OPENAI_API_KEY=sk-xxx
export OPENAI_API_BASE=https://api.moonshot.cn
export OPENAI_MODEL=moonshot-v1-8k
```

> **注意**：`OPENAI_API_BASE` 应指向服务的根地址（程序会自动拼接 `/v1/chat/completions`）。部分服务（如 Qwen）的 base 已包含 `/v1`，此时程序会拼接出 `/v1/v1/chat/completions`，需按各服务文档调整。

## 使用

```bash
./cagent
```

进入交互式 REPL：

```
cagent ready. model=deepseek-chat base=https://api.deepseek.com
type /help for commands, /exit to quit.

> 你好
你好！我是 cagent，有什么可以帮你的吗？

> 列出当前目录的文件
[tool: list_dir] args={"path":"."}
[tool: list_dir] -> {"entries":[{"name":"cagent","type":8},...]}
当前目录下有以下文件和目录：
- cagent（可执行文件）
- ...

> /exit
```

### 斜杠命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示命令帮助 |
| `/exit` | 保存历史并退出（EOF / Ctrl+D 同样） |
| `/save <path>` | 保存当前对话到指定文件 |
| `/load <path>` | 从文件加载对话 |
| `/clear` | 清空对话历史（保留默认 system prompt） |
| `/history` | 显示当前消息数量 |
| `/system <text>` | 追加一条 system 消息 |

### 内置工具

Agent 通过 function calling 自主调用以下工具：

| 工具 | 参数 | 说明 |
|------|------|------|
| `run_command` | `command: string` | 执行 shell 命令，返回 stdout（截断至 4KB） |
| `read_file` | `path: string` | 读取文本文件内容 |
| `write_file` | `path: string, content: string` | 写入文本文件（覆盖） |
| `list_dir` | `path: string`（默认 `.`） | 列出目录条目 |

工具执行过程会实时打印：
```
[tool: <name>] args=<json>
[tool: <name>] -> <result>
```

## 项目结构

```
agent/
├── CMakeLists.txt              # 构建脚本
├── README.md
├── AGENTS.md                   # AI 开发指南
├── include/
│   ├── utils.h                 # sbuf_t 动态字符串缓冲
│   ├── memory.h                # 消息历史 + tool_call_t 定义
│   ├── tools.h                 # 工具注册表 + tool_fn_t 签名
│   ├── sse.h                   # SSE 流式解析器
│   ├── llm.h                   # llm_config_t / llm_result_t / llm_chat
│   └── agent.h                 # agent_t / agent_run 主循环
├── src/
│   ├── utils.c                 # sbuf 实现
│   ├── memory.c                # 消息增删查 + JSON 序列化 + 文件 I/O
│   ├── tools.c                 # 4 个内置工具 + schema 构造
│   ├── sse.c                   # 跨 chunk 的 SSE 事件切分
│   ├── llm.c                   # libcurl POST + 流式/非流式响应解析
│   ├── agent.c                 # agent_step + tool_call 迭代循环
│   └── main.c                  # CLI REPL + 斜杠命令 + 环境变量配置
└── examples/
    └── tools_demo.json         # 工具 schema 示例（参考，不参与编译）
```

## 错误处理

- **网络错误**：`[llm] curl error: <说明>`，退出码对应 `LLM_ERR_NETWORK`
- **HTTP 非 2xx**：打印状态码 + 响应体前 1KB（便于诊断 401/404/429 等）
- **JSON 解析失败**：`[llm] failed to parse response JSON`
- **工具执行失败**：返回 `{"error":"..."}` 字符串给模型，模型自行处理
- **达到迭代上限**：`[agent] reached max iterations (10), stopping`

## 许可

MIT