v0.1: 梦开始的地方 —— LLM调用

README.md

@@ -0,0 +1,172 @@
+# AgentSeed
+
+> 播下一颗种子，期待它长成参天大树的那天。
+
+AgentSeed 是一个从零开始构建 AI Agent 的渐进式教学项目。
+
+项目以 Python 为主，不直接依赖 LangChain 等 Agent Framework，而是从一次最基础的 LLM 调用出发，逐步实现上下文、工具调用、Agent Loop、存储、检索、Skill、MCP、可观测性与评测。
+
+## 为什么做 AgentSeed
+
+AI 正在从单纯的聊天工具，转向能够理解目标、使用工具并完成任务的智能助手。
+
+一个 Agent 可以简单理解为：
+
+```text
+Agent = 大语言模型（LLM）+ 上下文（Context）+ 工具（Tools）
+```
+
+- **LLM** 负责理解问题、推理并作出决策；
+- **Context** 为模型提供完成当前任务所需的信息；
+- **Tools** 让模型能够搜索、计算、读写文件并调用外部服务。
+
+但在实际学习中，LLM、Tool Use、Agent Loop、RAG、Skill 和 MCP 等概念经常同时出现，让人难以看清它们之间的关系。
+
+AgentSeed 希望提供一条清晰的学习路径：不从庞大的框架开始，而是从可以运行的最小代码开始。每次只引入一个主要概念，观察它解决了什么问题，再让这些能力逐步生长为一个完整的 Agent。
+
+## 项目特点
+
+- **从底层机制开始**：直接理解 HTTP、JSON、Message、Tool Call 和 Agent Loop。
+- **渐进式实现**：项目能力通过连续的 Git commit 逐步演进。
+- **每步都可运行**：切换到关键提交后，可以观察该阶段新增的能力。
+- **先实践，再抽象**：抽象从已经运行的代码中产生，而不是提前设计复杂框架。
+- **覆盖完整链路**：从命令行模型调用，逐步扩展到 Web、RAG、Skill、MCP 和 Eval。
+
+## 如何学习
+
+本项目以 Git commit 作为学习和推进单位。每个关键提交都会回答四个问题：
+
+1. 这一阶段要解决什么问题？
+2. 为什么需要引入这个概念？
+3. 它在代码中是如何实现的？
+4. 运行后可以观察到什么新能力？
+
+你可以跟随主分支持续阅读，也可以切换到某个提交，查看 Agent 是如何一步步构建出来的。
+
+## 学习路线
+
+```text
+LLM 对话
+→ Agent 的执行、存储与检索
+→ 格式转换与可观测性
+→ Skill 技能系统
+→ MCP 协议接入
+→ 评测与最终整合
+```
+
+### 第一章：LLM 对话
+
+从一次普通的 HTTP 请求开始，理解应用如何与大语言模型通信。
+
+主要内容：
+
+- 调用 OpenAI-compatible 模型接口；
+- 理解 System、User、Assistant 消息角色；
+- 保存消息并实现上下文记忆；
+- 抽象模型客户端；
+- 实现流式输出；
+- 使用 FastAPI 和 React 构建 Web ChatBox。
+
+本章的目标是建立完整的模型通信基础，并理解：
+
+> LLM 的输入是一组有角色、有顺序的消息；所谓对话记忆，本质上是应用对上下文的保存与再次发送。
+
+### 第二章：Agent 核心能力
+
+在模型对话的基础上，引入 Agent 的三类核心能力：执行、存储与检索。
+
+#### 执行（Action）
+
+- 定义并调用 Tool；
+- 实现“模型决策 → 工具执行 → 结果反馈”的 Agent Loop；
+- 使用 Human-in-the-loop 审批关键操作。
+
+#### 存储（Storage）
+
+- 持久化保存会话和运行数据；
+- 使用检查点恢复被暂停或中断的 Agent。
+
+#### 检索（Retrieval）
+
+- 从线性遍历和关键词检索开始；
+- 逐步引入全文索引与向量索引；
+- 使用 RAG 将外部知识注入模型上下文。
+
+本章的目标是让模型从“生成回答”走向“采取行动并使用外部知识”。
+
+### 第三章：格式转换与可观测性
+
+让 Agent 的输入、输出和执行过程更加可靠、清晰和可追踪。
+
+主要内容：
+
+- 使用 Schema 约束结构化输出；
+- 记录模型调用、工具执行和停止原因；
+- 保存并查看完整的 Agent 运行轨迹。
+
+本章的目标是解决两个问题：Agent 输出能否被程序稳定使用，以及一次任务失败后能否看清发生了什么。
+
+### 第四章：Skill 技能系统
+
+让 Agent 根据任务按需发现和使用可复用的技能说明。
+
+主要内容：
+
+- 从文件系统发现并激活 Skill；
+- 按需加载 Skill 指令和资源；
+- 使用 Skill 编排多步骤任务；
+- 复用已有的 Agent Loop、Tools 和结构化输出能力。
+
+本章的目标是让 Agent 从通用执行器进一步发展为能够按任务加载专业工作方法的系统。
+
+### 第五章：MCP 协议接入
+
+通过 Model Context Protocol 将 Agent 与外部能力连接起来。
+
+主要内容：
+
+- 管理 MCP Server 的生命周期；
+- 发现并调用 MCP Tool；
+- 连接多个受信任的 MCP Server；
+- 将 MCP Resource 和 Prompt 加入上下文。
+
+本章的目标是理解 MCP 如何为模型与外部工具、资源和提示词提供统一的连接方式。
+
+### 第六章：评测与最终整合
+
+将前面实现的能力组合为完整的 Agent 参考应用，并建立可重复的验证方法。
+
+主要内容：
+
+- 构建可确定性验证的 Eval Runner；
+- 统计成功率、步骤数、耗时和用量；
+- 整合 CLI、Web、Tool、RAG、Skill、MCP 和 Trace；
+- 提供端到端示例与调试说明。
+
+本章的目标是让 Agent 不仅“能够运行”，还能够被验证、分析和持续改进。
+
+## 阶段产物
+
+| 阶段 | 主题 | 阶段产物 |
+| --- | --- | --- |
+| 1 | LLM 对话 | 支持消息角色、上下文和流式响应的 CLI 与 Web ChatBox |
+| 2 | Agent 核心能力 | 支持 Tool、人工审批、持久化、恢复和 RAG 的 Agent |
+| 3 | 格式与可观测性 | 结构化输出与可查看的 Agent Trace |
+| 4 | Skill 技能系统 | 支持技能发现与多步骤任务的 Skill Agent |
+| 5 | MCP 协议 | 支持 Tools、Resources、Prompts 和多服务路由的 MCP Agent |
+| 6 | 评测与整合 | Eval Runner、参考应用与端到端教程 |
+
+## 项目原则
+
+- 使用渐进式单项目，让能力在前一个提交的基础上自然演进；
+- 每个关键提交聚焦一个主要概念和一项可观察的新能力；
+- 不使用大型 Agent Framework 隐藏关键机制；
+- 先理解模型通信和 Agent 原理，再逐步完成工程抽象；
+- 不为尚未出现的问题提前引入复杂设计；
+- 不提交 API Key 或其他敏感信息。
+
+## 最终目标
+
+AgentSeed 最终会形成一个完整但最小的 AI Agent 参考实现：它能够与模型对话、维护上下文、调用工具、等待人工审批、保存与恢复状态、检索外部知识、加载 Skill、连接 MCP Server，并通过 Trace 和 Eval 观察与验证自己的执行过程。
+
+更重要的是，项目会完整保留它从一颗种子逐步生长起来的过程。

main.py

@@ -0,0 +1,25 @@
+import os
+import httpx
+
+# 获取模型服务地址、访问密钥和模型名称。
+base_url = os.environ["OPENAI_BASE_URL"]
+api_key = os.environ["OPENAI_API_KEY"]
+model = os.environ["OPENAI_MODEL"]
+
+while True: # 持续接收用户输入，实现最基础的命令行对话。
+    user_input = input("You> ")
+
+    # 按照 OpenAI Chat Completions 协议向模型服务发送 HTTP 请求。
+    response = httpx.post(
+        f"{base_url.rstrip('/')}/chat/completions",
+        headers={"Authorization": f"Bearer {api_key}"}, # 认证信息
+        json={
+            "model": model, # 选择的模型名称
+            "messages": [{"role": "user", "content": user_input}], # 用户输入的消息
+        },
+        timeout=60,
+    )
+
+    # 将 JSON 响应转换为字典，然后取出模型生成的文本。
+    data = response.json()
+    print("Assistant>", data["choices"][0]["message"]["content"])

pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "agentseed"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27,<1",
+    "python-dotenv>=1,<2",
+]