# smolagents-example

**Repository Path**: bytesifter/smolagents-example

## Basic Information

- **Project Name**: smolagents-example
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# smolagents-example

基于 HuggingFace [smolagents](https://github.com/huggingface/smolagents) 的 **ReAct Agent 学习示例**，包含四个独立 demo，从框架到手写逐步深入。

**ReAct（Reasoning + Acting）** 是一种让 LLM 交替进行"推理"和"行动"的 Agent 框架：
`Thought（推理）→ Action（行动）→ Observation（观测）` 循环往复，直到解决问题。

## 学习路线

建议按以下顺序学习，从底层原理到框架应用：

| 步骤 | Demo | 模块 | 学习重点 |
|------|------|------|---------|
| 1 | **手写 ReAct**（零框架） | `03_scratch` | 底层原理最透彻 |
| 2 | **CodeAgent 可见化** | `01_code_agent` | Code-ReAct 变体 |
| 3 | **经典 JSON ReAct** | `02_tool_calling_agent` | 经典 ReAct 格式 |
| 4 | **Planning 增强** | `04_planning` | 先规划后执行 |

## 快速开始

```bash
# 1. 安装依赖
uv sync

# 2. 配置 API
cp .env.example .env
# 编辑 .env，填入你的 OPENAI_API_KEY

# 3. 运行任意 demo（以 03_scratch 为例，推荐从它开始）
uv run python -m src.03_scratch.main
```

## Demo 介绍

### 手写 ReAct —— `03_scratch`

**完全不依赖任何 Agent 框架**，仅用 `openai` SDK 手动实现完整 ReAct 循环，是理解 ReAct 最透彻的方式。

包含：
- 手动构造 **ReAct 系统提示词**（含少样本示例）
- 从 LLM 响应中解析 **Action / Action Input**
- 工具注册表（工具名 → 函数映射）
- Thought → Action → Observation 循环，直到 `final_answer`

```bash
uv run python -m src.03_scratch.main
```

### CodeAgent 可见化 —— `01_code_agent`

基于 smolagents 的 **CodeAgent**，通过 hook `model.generate` 和 `python_executor` 使 ReAct 循环的每一环节对用户完全可见。

CodeAgent 的 Action 形式是 **Python 代码**，而非 JSON tool call。可以在一次代码块中调用多个工具、使用循环和条件判断。

```bash
uv run python -m src.01_code_agent.main
```

### 经典 JSON ReAct —— `02_tool_calling_agent`

基于 smolagents 的 **ToolCallingAgent**，Action 是结构化的 JSON tool call，更符合原始 ReAct 论文中的定义。

```bash
uv run python -m src.02_tool_calling_agent.main
```

### Planning 增强 —— `04_planning`

基于 CodeAgent + `planning_interval=3`，在每 N 步之前让 LLM 先做 **facts survey（事实调查）** 和 **plan（规划）**，再执行动作。展示元认知层的工作方式。

```bash
uv run python -m src.04_planning.main
```

## 四种方案对比

| 模块 | 名称 | 框架依赖 | Action 形式 | 学习重点 |
|------|------|---------|-----------|---------|
| `03` | **手写 ReAct** | **无** | **文本 Action** | **底层原理（推荐）** |
| `01` | CodeAgent 可见化 | smolagents | Python 代码 | Code-ReAct 变体，多工具调用，控制流 |
| `02` | 经典 JSON ReAct | smolagents | JSON tool call | 经典 ReAct，结构化 Action |
| `04` | Planning 增强 | smolagents | Python 代码 | 元认知层：facts survey + plan |

## 配置说明

通过 `.env` 文件配置（参考 `.env.example`）：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_API_KEY` | API 密钥 | （必填） |
| `OPENAI_BASE_URL` | API 地址 | `https://api.openai.com/v1` |
| `OPENAI_MODEL` | 模型名称 | `gpt-4o` |

支持任何兼容 OpenAI API 的服务（OpenAI、DeepSeek、通义千问 等），只需修改 `BASE_URL` 和 `MODEL`。

## 使用示例

```bash
$ uv run python -m src.01_code_agent.main
============================================================
  [01_code_agent] 可见化的 CodeAgent ReAct Demo
  输入问题后，Agent 会展示完整的 ReAct 循环：
  Thought → Code → Observation → ... → Final Answer
============================================================

> 1+1 等于几？
...
```