# agent-learning

**Repository Path**: jovan_yang/agent-learning

## Basic Information

- **Project Name**: agent-learning
- **Description**: agent demo仓库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Coding Agent — 编码智能体学习项目

基于 **LangChain**、**LangGraph**、**LangSmith** 的通用编码 Agent 演示项目，帮助你系统学习 Agent 开发。

## 技术栈

| 组件 | 用途 |
|------|------|
| LangChain | LLM 抽象、Tool 定义、消息模型 |
| LangGraph | Agent 状态图、ReAct 循环编排 |
| LangSmith | 追踪、调试、评估 Agent 运行 |
| OpenAI 兼容 API | 支持 OpenAI / Moonshot / DeepSeek 等 |

## 快速开始

### 前置要求

- [uv](https://docs.astral.sh/uv/)（推荐 `pip install uv` 或见官方安装文档）
- Python 3.13+（项目通过 `.python-version` 指定 3.14，由 uv 自动管理）

### 1. 安装依赖

```bash
# 安装 uv 后，在项目根目录执行（会创建 .venv 并生成/使用 uv.lock）
uv sync
```

仅安装生产依赖（不含测试工具）：

```bash
uv sync --no-dev
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 LLM_API_KEY 等配置
```

### 3. 运行 Agent

```bash
# 交互模式
uv run python main.py

# 或使用已注册的命令行入口
uv run coding-agent

# 单次任务
uv run python main.py --once "列出项目结构并说明各模块职责"

# 流式观察 ReAct 过程
uv run python main.py --stream

# 使用手写 LangGraph（学习 Graph 编排）
uv run python main.py --mode custom
```

### 常用 uv 命令

```bash
uv add requests              # 添加依赖
uv add --dev httpx           # 添加开发依赖
uv lock                      # 更新锁文件
uv run pytest -v             # 在虚拟环境中运行命令
```

## 项目结构

```
agent-learning/
├── pyproject.toml          # 项目与依赖声明
├── uv.lock                 # uv 依赖锁文件
├── .python-version         # Python 版本（uv 管理）
├── main.py                 # CLI 入口
├── config/settings.yaml    # YAML 配置
├── src/
│   ├── agent/
│   │   ├── coding_agent.py   # Agent 封装（prebuilt / custom）
│   │   ├── custom_graph.py   # 手写 LangGraph（学习重点）
│   │   ├── prompts.py        # 系统提示词
│   │   └── state.py          # Graph 状态定义
│   ├── tools/
│   │   ├── file_tools.py     # 文件读写、目录浏览
│   │   ├── search_tools.py   # 代码搜索
│   │   ├── shell_tools.py    # Shell 命令执行
│   │   └── registry.py       # 工具注册
│   ├── llm/factory.py        # LLM 工厂
│   └── utils/config.py       # 配置加载
└── tests/
```

## 学习路径

建议按以下顺序阅读代码：

1. **`src/tools/`** — 理解 LangChain `@tool` 装饰器与工具设计
2. **`src/agent/prompts.py`** — 系统提示词如何约束 Agent 行为
3. **`src/agent/coding_agent.py`** — `create_react_agent` 快速搭建 ReAct Agent
4. **`src/agent/custom_graph.py`** — 手写 StateGraph，理解节点/边/条件路由
5. **`src/utils/config.py`** — LangSmith 追踪配置

## LangSmith 调试

在 [smith.langchain.com](https://smith.langchain.com) 注册后，在 `.env` 中配置：

```
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=coding-agent-learning
```

每次 Agent 运行都会在 LangSmith 中留下完整 trace，包括每轮 LLM 调用、工具入参和返回。

## Agent 工具一览

| 工具 | 说明 |
|------|------|
| `read_file` | 读取工作区文件（支持行号范围） |
| `write_file` | 写入/覆盖文件 |
| `list_directory` | 列出目录内容 |
| `get_project_structure` | 生成目录树 |
| `search_in_files` | 正则搜索代码 |
| `find_files` | 按 glob 查找文件 |
| `run_shell_command` | 执行 Shell 命令（带安全拦截） |

## 两种 Graph 模式

- **`prebuilt`**（默认）：使用 `langgraph.prebuilt.create_react_agent`，适合快速上手
- **`custom`**：手写 `StateGraph`，展示 ReAct 循环的底层实现，适合深入理解 LangGraph

## 运行测试

```bash
uv run pytest -v
```

## 示例任务

```
分析 src/agent/ 目录的代码结构，画出 ReAct 循环流程
在 tests/ 下添加一个测试 utils/config.py 的用例
搜索项目中所有 @tool 装饰器并总结工具设计模式
运行 pytest 并解释失败的测试
```

## 延伸阅读

- [LangChain Agents 文档](https://python.langchain.com/docs/concepts/agents/)
- [LangGraph 教程](https://langchain-ai.github.io/langgraph/tutorials/)
- [LangSmith 文档](https://docs.smith.langchain.com/)