# Single Agent Demo

**Repository Path**: kumei/single-agent-demo

## Basic Information

- **Project Name**: Single Agent Demo
- **Description**: 一个 Agent Demo，接入 DeepSeek，包含：
- Agent 执行循环：模型选择工具 → 程序执行 → 结果回传 → 继续或回答。
- 三个工具：计算器、本地知识检索、保存笔记。
- 多轮对话、调用日志、错误处理和执行次数限制。
- 中文 README、配置模板、离线演示与测试。
- **Primary Language**: Android
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeepSeek Single-Agent 可运行 Demo

这是一个 Python 3.10+ 命令行项目，只用标准库，无需 pip 安装依赖。
一个模型自主选择工具，宿主程序执行并回传结果，循环到模型生成答案。
包含对话历史、3个工具、本地检索、错误回传、执行次数限制、API 错误提示和离线测试。

## 1. 最快体验：不需要 API Key

解压后，终端进入项目目录：

```bash
cd deepseek-single-agent
python agent.py --mock-demo
```

部分 macOS/Linux 环境需要将 python 换为 python3。
离线模式是固定脚本，不调用 DeepSeek，也不能处理任意任务；用于验证工具循环和运行环境。
你会看到模型请求、calculate 调用、search_knowledge 调用、工具结果和最终答案。

## 2. 接入真实 DeepSeek

在 https://platform.deepseek.com/ 获取 API Key，并确保 API 账户有可用余额。
复制 `.env.example` 为 `.env`，填入自己的 Key。不要把 Key 发到聊天或提交 Git。

Windows PowerShell：

```powershell
Copy-Item .env.example .env
notepad .env
python agent.py
```

macOS/Linux：

```bash
cp .env.example .env
# 用文本编辑器填写 .env
python3 agent.py
```

配置内容：

```dotenv
DEEPSEEK_API_KEY=你的真实APIKey
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-flash
```

模型名称依据 2026-10-10 查阅的官方快速入门文档；后续可改为自己账户支持工具调用的模型。
本 Demo 显式关闭 thinking，采用非流式 Chat Completions。
如果使用旧模型或第三方兼容服务，请确认其支持 thinking 参数；不支持时删除 agent.py 请求体中的 thinking 字段。
已有环境变量优先于 `.env`；换 Key 后仍出现401时检查系统环境变量。

交互示例：

```text
你：车费120元，门票80元，10个人均摊，人均多少？
你：从本地资料查询 Repository 与 DataSource 的区别。
你：把刚才的职责区别保存为 architecture.md 笔记。
你：/reset
你：/exit
```

一次性任务：

```bash
python agent.py --ask "查询本地资料，解释 Single-Agent 与 Tool Use 的关系"
```

保存笔记位于 `data/notes/`。同名文件不会覆盖，可指定另一个名字。
真实模型的选择可能不同，但计算和本地知识问题的工具使用规则已写入系统提示。

## 3. 代码对应哪些 Agent 知识点？

| 知识点 | 本 Demo 的位置 | 通俗理解 |
| --- | --- | --- |
| System | agent.py 的 SYSTEM | 给助手规定职责和规则 |
| Messages | SingleAgent.messages | 每次请求携带的聊天记录 |
| Tool schema | tools.py 的 TOOLS | 给模型看的工具说明书 |
| Tool Use | tools.py 的 execute | 模型提请求，Python 真正干活 |
| Agent Loop | SingleAgent.ask | 反复询问模型，直到有最终答案 |
| Observation | role=tool 的消息 | 把干活结果交给模型 |
| RAG | search_knowledge | 先查本地资料，再回答 |
| Memory | SingleAgent.turns | 最近10轮完整对话，进程内记忆 |
| Guardrails | 参数验证、文件名限制、步数限制 | 给执行过程设边界 |
| 可观测性 | 控制台调用日志 | 看到哪个工具被调用、返回了什么 |

这里有 ReAct 风格的“行动—观察—再决策”循环，但不要求模型暴露思维链。
日志是工具调用记录，不是模型内部思考。

具体执行过程：
1. 用户输入写入 user 消息。
2. 系统规则、历史和工具说明一起送给 DeepSeek。
3. 若模型返回 tool_calls，先保留完整 assistant 消息。
4. 程序逐个执行工具，每个结果带原来的 tool_call_id，作为 tool 消息追加。
5. 再请求模型；它可以继续调用工具，也可以输出最终答案。
6. 完成后保存整个轮次，下次对话带上最近历史。

一个模型可以调用很多工具，因此多个工具不代表 Multi-Agent。
模型不会直接执行 Python，也不会凭空读取你电脑上的资料。

## 4. 文件结构与扩展

- agent.py：HTTP客户端、配置加载、Agent循环、命令行和离线模拟。
- tools.py：工具声明、工具实现、参数验证和统一错误包装。
- knowledge/*.md：可自行补充的本地知识资料。
- tests/test_agent.py：离线协议和边界验证。
- .env.example：配置模板；真实 .env 不包含在压缩包中。

新增工具需要做两件事：实现函数并加入 FUNCTIONS，然后在 TOOLS 加上模型能理解的 JSON schema。
可先把 Android 项目的知识写成 knowledge 下的 Markdown，体验检索效果。

运行测试：

```bash
python -m unittest discover -s tests -v
```

## 5. 边界和排错

- 这是一份完整教学 Demo，不是生产系统：没有用户登录、向量数据库、联网搜索、流式输出或持久化聊天历史。
- RAG 使用关键词片段匹配，语义召回有限；资料内容会随工具结果发送给 DeepSeek。
- 最多8次模型请求、24次工具调用；保留10轮不是精确 token 裁剪。
- 单条用户输入最多12000字符，笔记最多10000字符，计算不使用 eval。
- 工具仅允许已注册函数；保存仅在固定 notes 目录独占创建，不执行系统命令。
- 保存笔记基于系统提示要求用户明确请求；这不是对抗恶意输入的完整权限系统。生产环境应对写操作加入宿主侧确认和授权。
- 失败轮次不进入历史；已写入笔记不回滚。失败后可检查 notes 目录，避免误以为没有执行。
- 401检查Key；402检查余额；429稍后重试；400检查模型/参数/上下文长度。
- 超时不会自动重试，避免不确定情况下重复请求。每次工具循环可能产生多次API费用。
- /reset 只清空聊天，不删除笔记；控制台日志可能含用户输入和工具内容。

验证情况：已运行离线演示、7项单元测试（包括模拟HTTP格式）。没有用户API Key，尚未执行真实DeepSeek端到端请求。

## 官方参考

- https://api-docs.deepseek.com/ — API 地址、模型名与快速入门。
- https://api-docs.deepseek.com/guides/tool_calls/ — tool_calls 和工具结果回传协议。