# llm-to-agent-tutorial

**Repository Path**: buptnetwork/llm-to-agent-tutorial

## Basic Information

- **Project Name**: llm-to-agent-tutorial
- **Description**: 这是一个循序渐进的 Python 代码仓库，旨在帮助开发者从零开始，一步步掌握 AI Agent（智能体）的底层原理与工程化开发。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

欢迎来到 AI Agent Cookbook！这是一个循序渐进的 Python 代码仓库，旨在帮助开发者从零开始，一步步掌握 AI Agent（智能体）的底层原理与工程化开发。

本仓库拒绝黑盒，我们不仅教你如何使用框架，更会通过剥离框架的原生代码，让你真正理解 Agent 的运行机制。

🗺️ 学习路线图 (Learning Path)
本项目的代码按照从易到难、从底层到高层的逻辑组织。建议按照以下顺序进行学习：

01 基础底层机制
原生API/Function Calling

02 LangChain 核心
LCEL/工具绑定/结构化输出

03 经典 Agent
ReAct 模式/自定义工具

04 LangGraph 基础
状态机/条件路由/人在回路

05 工程与部署
Streamlit/FastAPI

📁 目录导览
01_basic_llm_api - 筑基篇：理解大模型底层逻辑
不依赖重型框架，纯手写实现 Function Calling（函数调用），这是所有 Agent 的基石。
02_langchain_fundamentals - 进阶篇：LangChain 核心组件
掌握 LCEL 语法、工具封装 (@tool)、以及结构化输出 (Structured Output)。
03_basic_agents - 智能体篇：让 AI 开始自主思考
实现经典的 ReAct Agent，观察 AI 如何遵循 "思考-行动-观察" 的循环。
04_langgraph_basics - 高阶篇：用图结构掌控流程
引入 LangGraph，解决传统 Agent 容易死循环的问题，实现“人在回路”(Human-in-the-loop)。
05_deployment_and_ui - 工程篇：打包与展示
使用 Streamlit 和 FastAPI 将你的 Agent 转化为可视化应用和 API 服务。


🚀 快速开始 (Quick Start)

本项目使用 [uv](https://docs.astral.sh/uv/) 管理依赖和虚拟环境。

1. 安装 uv（如尚未安装）

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

2. 克隆仓库

```bash
git clone https://github.com/your-username/ai-agent-cookbook.git
cd ai-agent-cookbook
```

3. 创建虚拟环境并安装依赖

```bash
# uv 会自动创建 .venv 并安装所有依赖
uv sync
```

4. 环境变量配置

在项目根目录复制一份环境变量示例文件，并填入你的 API Key：

```bash
cp .env.example .env
```

.env 文件内容示例：

```env
# 必须：大模型 API (默认以 OpenAI 为例，也可替换为其他兼容模型)
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"
# OPENAI_BASE_URL="https://api.openai.com/v1" # 如果需要国内代理请取消注释
# 可选：Tavily API (用于 Agent 联网搜索工具)
# 申请地址: https://tavily.com/
TAVILY_API_KEY="tvly-xxxxxxxxxxxxxxxxxxxx"
# 强烈推荐：LangSmith 监控 (用于 Agent 过程调试)
# 申请地址: https://smith.langchain.com/
LANGCHAIN_TRACING_V2="true"
LANGCHAIN_API_KEY="lsv2_xxxxxxxxxxxxxxxxxxxx"
LANGCHAIN_PROJECT="ai-agent-cookbook"
```

5. 运行你的第一个示例

```bash
uv run python 01_basic_llm_api/01_chat_completion.py
```

如需运行 Streamlit 应用：

```bash
uv run streamlit run 05_deployment_and_ui/01_streamlit_app.py
```
💡 开发者建议：拥抱 LangSmith
Agent 开发与传统软件开发不同，AI 的思考过程是动态且不可预测的。当 Agent 跑飞或者陷入死循环时，纯靠 print 调试会让人崩溃。

项目中已经集成了对 LangSmith 的支持。强烈建议你在 .env 中开启 LANGCHAIN_TRACING_V2=true，你将在浏览器界面中清晰地看到 Agent 每一步的思考 (Thought)、工具调用 (Tool Call) 的入参和出参。