快速上手

Q: 没有 OpenAI Key 能学吗？

多数模块可用 DEEPSEEK_API_KEY 等兼容 OpenAI 接口的密钥替代；纯本地模块（如 Ollama / LM Studio）无需任何云端 Key。

Q: 依赖装不上怎么办？

确认 Python 版本在 3.10–3.12 区间，并使用独立虚拟环境；必要时参考仓库 CONTRIBUTING.md 与 Issue 区。

五分钟，从空环境到跑通你的第一个可运行 AI Agent。

💡 先读一句本教程所有模块都「代码可运行」。只要按下面三步准备好环境，你就能在本地复现每一个示例，而不是只看不练。

前置要求

Python 3.10 – 3.12：推荐用 venv 或 conda 建独立环境。
Node.js v20+：部分模块（如 MCP Streamable HTTP、前端）会用到。
一个 LLM API Key：至少准备 OPENAI_API_KEY，其余按需。
Git：用于克隆仓库。

三步跑通

环境准备：克隆并安装依赖

克隆仓库后安装 requirements.txt，并以开发者模式安装本项目（pip install -e .），这样模块间可以相互 import。

bash

git clone https://github.com/Annyfee/agent-craft.git
cd agent-craft
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

API Key 配置

复制环境变量模板，按需填入密钥。OPENAI_API_KEY 为必填，其余（DeepSeek / LangSmith / 高德地图 / ChatGPT）按模块需要填写。

bash

cp .env.example .env
# 编辑 .env，至少填入：
# OPENAI_API_KEY=sk-xxx
# DEEPSEEK_API_KEY=sk-xxx        # 可选
# LANGSMITH_API_KEY=xxx          # 可选，用于追踪
# AMAP_MAPS_API_KEY=xxx          # 可选，地图工具

运行你的第一个示例

进入模块目录直接运行示例脚本，看到模型返回即代表环境就绪。

bash

python "m01_agent_introduction/Agent-demo.py"

目录结构

仓库按模块分目录，每个模块独立、可运行：

tree

agent-craft/
├── m01_agent_introduction/   # 模块 01：入门与环境
├── m02_llm_fundamentals/     # 模块 02：LLM 基础调用
├── m03_function_calling_tools/
├── m04_langchain_basics/
├── ...                       # 一直到 m13_streamlit
├── .env.example              # 环境变量模板
├── requirements.txt          # 依赖清单
├── setup.py                  # 开发者模式安装
└── embeddings.py             # 嵌入相关工具

✅ 跑通后建议从模块文档按顺序学习，或先看学习路径理解整体能力地图。遇到问题欢迎到社区提 Issue。

常见问题

Q：没有 OpenAI Key 能学吗？

多数模块可用 DEEPSEEK_API_KEY 等兼容 OpenAI 接口的密钥替代；纯本地模块（如 Ollama / LM Studio）无需任何云端 Key。

Q：Node 必须装吗？

基础与框架篇主要用 Python；MCP 的 Streamable HTTP 传输、Streamlit 前端等会用到 Node 20+，建议提前装好。

Q：依赖装不上？

确认 Python 版本在 3.10–3.12 区间，并使用独立虚拟环境；必要时参考仓库 CONTRIBUTING.md 与 Issue 区。