[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2224":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":13,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},2224,"Agent-template","zhuqn1021\u002FAgent-template","zhuqn1021"," 一个开箱即用的现代化的 AI Agent 项目模板，采用分层架构设计，包含LLM 多模型抽象层、Tools 工具链系统、Skills 技能系统、Agent 核心层 、RAG 检索增强多路召回、Memory 记忆系统、 配置系统、以及多Agent编排示例等企业级功能。","https:\u002F\u002Fgithub.com\u002Fzhuqn1021\u002FAgent-template",null,"Python",85,5,117,0,60,180,2.33,false,"main",true,[],"2026-06-12 02:00:38","# Agent Template 项目指南\n\n> 一个面向生产原型的 Python AI Agent 项目模板，内置多模型切换、Function Calling 工具调用、RAG 多路召回、对话记忆、LangGraph 编排示例，以及完整执行过程 Trace 复盘能力。\n\n---\n\n## 能力概览\n\n- **多模型抽象**：统一封装 DashScope 和 OpenAI 兼容接口，支持 DeepSeek、GLM、Moonshot、Ollama 等。\n- **Agent 分层**：提供纯对话 `ChatAgent` 和支持 ReAct 工具循环的 `TaskAgent`。\n- **工具系统**：基于 OpenAI Function Calling schema，支持工具注册、自动执行、结果回传。\n- **RAG 增强**：支持 Qdrant 向量检索、关键词召回、多路召回、RRF 融合排序。\n- **记忆系统**：支持本地内存和 Redis 滑动窗口记忆。\n- **LangGraph 示例**：展示如何把检索、规划、工具调用、回答生成编排成显式图流程。\n- **Trace 复盘**：记录一次请求中的 RAG、Memory、LLM、Tool 调用全过程，便于排查和评估。\n\n---\n\n## 目录结构\n\n```text\nagent_template\u002F\n├── agents\u002F                         # Agent 核心层\n│   ├── base.py                      # AgentBase + AgentResponse\n│   ├── chat_agent.py                # 对话型 Agent\n│   └── task_agent.py                # ReAct 工具调用 Agent\n│\n├── config\u002F                         # 配置管理\n│   ├── loader.py                    # YAML + ENV 配置加载\n│   ├── settings.py                  # dataclass 配置结构\n│   ├── settings.yaml                # 基础配置\n│   └── settings.development.yaml    # 开发环境覆盖配置\n│\n├── examples\u002F                       # 示例代码\n│   ├── chat_example.py              # 基础对话\n│   ├── tool_agent_example.py        # 工具调用\n│   ├── model_switch_example.py      # 模型热切换\n│   ├── rag_example.py               # RAG 多路召回问答\n│   ├── multi_agent_example.py       # 多 Agent 协作\n│   └── langgraph_orchestration_example.py # LangGraph 编排\n│\n├── llm\u002F                            # LLM 多模型抽象层\n│   ├── base.py                      # ChatMessage \u002F LLMResponse \u002F LLMBase\n│   ├── dashscope_llm.py             # DashScope 实现\n│   ├── openai_llm.py                # OpenAI 兼容实现\n│   └── factory.py                   # LLMFactory \u002F create_llm\n│\n├── memory\u002F                         # 对话记忆\n│   ├── base.py                      # MemoryBase\n│   ├── local_memory.py              # 本地内存记忆\n│   └── redis_memory.py              # Redis 记忆\n│\n├── rag\u002F                            # RAG 检索增强\n│   ├── embeddings.py                # DashScope\u002FOpenAI Embedding\n│   ├── vector_store.py              # Qdrant 向量存储\n│   └── retriever.py                 # 向量召回、关键词召回、多路召回\n│\n├── skills\u002F                         # 可复用 LLM 技能\n│   ├── base.py\n│   ├── json_extractor.py\n│   ├── document_parser.py\n│   └── report_generator.py\n│\n├── tools\u002F                          # Function Calling 工具系统\n│   ├── base.py                      # Tool \u002F ToolResult\n│   ├── registry.py                  # ToolRegistry\n│   └── builtin\u002F\n│       ├── code_executor.py         # Python 代码执行工具\n│       ├── file_reader.py           # 文件读取工具\n│       └── web_search.py            # 搜索工具示例桩\n│\n├── utils\u002F                          # 通用工具\n│   ├── json_parser.py               # JSON 容错解析\n│   ├── logger.py                    # 标准日志\n│   ├── prompt_loader.py             # Prompt 模板加载\n│   └── tracing.py                   # Agent 执行 Trace\n│\n├── prompts\u002F                        # Prompt 模板目录\n├── main.py                         # FastAPI 服务入口\n├── requirements.txt                # Python 依赖\n└── .env.example                    # 环境变量模板\n```\n\n---\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\npip install -r requirements.txt\n```\n\n### 2. 配置 API Key\n\n复制环境变量模板：\n\n```bash\ncp .env.example .env\n```\n\n至少配置：\n\n```bash\nAGENT_ENV=development\nAGENT_LLM_API_KEY=your-api-key\n```\n\n默认配置使用 DashScope：\n\n```yaml\nllm:\n  provider: \"dashscope\"\n  model: \"qwen-plus\"\n```\n\n如果使用 DeepSeek、GLM、Moonshot、Ollama 等 OpenAI 兼容接口，将 `provider` 改为 `openai` 并配置 `base_url`。\n\n### 3. 启动 FastAPI 服务\n\n```bash\nuvicorn main:app --reload --port 8000\n```\n\n健康检查：\n\n```bash\ncurl http:\u002F\u002Flocalhost:8000\u002Fhealth\n```\n\n对话请求：\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:8000\u002Fchat \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"message\": \"你好\", \"session_id\": \"test\"}'\n```\n\n响应示例：\n\n```json\n{\n  \"reply\": \"你好！有什么可以帮你？\",\n  \"session_id\": \"test\",\n  \"trace_id\": \"...\"\n}\n```\n\n`trace_id` 可用于定位 `traces\u002Fagent_runs.jsonl` 中的完整执行记录。\n\n---\n\n## 配置系统\n\n配置加载入口是 `config.loader.get_settings()`，优先级从低到高：\n\n1. `config\u002Fsettings.py` 中的 dataclass 默认值\n2. `config\u002Fsettings.yaml`\n3. `config\u002Fsettings.{env}.yaml`\n4. `AGENT_` 前缀环境变量\n\n环境变量映射规则：\n\n```text\nAGENT_LLM_API_KEY       -> settings.llm.api_key\nAGENT_RAG_QDRANT_HOST   -> settings.rag.qdrant_host\nAGENT_MEMORY_REDIS_URL  -> settings.memory.redis_url\nAGENT_ENV               -> 当前环境名称\n```\n\n配置加载器会把环境变量中的 `int`、`float`、`bool`、`list` 字符串转换为 dataclass 字段对应类型。\n\n---\n\n## LLM 多模型抽象\n\n核心对象：\n\n- `ChatMessage`：统一消息结构\n- `LLMResponse`：统一模型响应结构，包含内容、tool_calls、token、finish_reason\n- `LLMBase`：所有模型 Provider 的抽象基类\n- `LLMFactory` \u002F `create_llm`：模型工厂\n\n支持的 Provider：\n\n| Provider | 模型示例 | 配置方式 |\n| --- | --- | --- |\n| DashScope | qwen-plus, qwen-turbo, qwen-max | `provider: \"dashscope\"` |\n| OpenAI | gpt-4o, gpt-4.1 | `provider: \"openai\"` |\n| DeepSeek | deepseek-chat | `provider: \"openai\"` + `base_url` |\n| GLM | glm-4 | `provider: \"openai\"` + `base_url` |\n| Moonshot | moonshot-v1-8k | `provider: \"openai\"` + `base_url` |\n| Ollama | qwen2:7b, llama3 | `provider: \"openai\"` + 本地 `base_url` |\n\n使用示例：\n\n```python\nfrom llm import ChatMessage, LLMFactory\n\nllm = LLMFactory.create(\n    provider=\"openai\",\n    model=\"deepseek-chat\",\n    api_key=\"sk-xxx\",\n    base_url=\"https:\u002F\u002Fapi.deepseek.com\u002Fv1\",\n)\n\nresponse = await llm.generate([\n    ChatMessage(role=\"user\", content=\"你好\")\n])\nprint(response.content)\n```\n\n运行时切换模型：\n\n```python\nagent.llm = LLMFactory.create(\n    provider=\"openai\",\n    model=\"deepseek-chat\",\n    api_key=\"sk-xxx\",\n    base_url=\"https:\u002F\u002Fapi.deepseek.com\u002Fv1\",\n)\n```\n\n---\n\n## Agent 层\n\n### ChatAgent\n\n适合客服、问答、咨询、知识库助手等纯对话场景。\n\n流程：\n\n```text\nsystem prompt -> RAG 可选 -> memory history -> user input -> LLM -> save memory -> response\n```\n\n示例：\n\n```python\nfrom agents import ChatAgent\nfrom memory import LocalMemory\n\nagent = ChatAgent(\n    llm=llm,\n    memory=LocalMemory(max_history=20),\n    retriever=retriever,\n    system_prompt=\"你是一个中文 AI 助手。\",\n)\n\nresponse = await agent.chat(\"介绍一下这个项目\", session_id=\"user_1\")\nprint(response.content)\nprint(response.metadata[\"trace_id\"])\n```\n\n### TaskAgent\n\n适合需要工具调用的任务，例如搜索、代码执行、文件读取、业务 API 调用。\n\n流程：\n\n```text\nuser input\n  -> LLM with tool schemas\n  -> tool_calls?\n      -> execute tools\n      -> append tool results\n      -> LLM again\n  -> final answer\n```\n\n示例：\n\n```python\nfrom agents import TaskAgent\nfrom tools import ToolRegistry\nfrom tools.builtin import CodeExecutorTool, FileReaderTool\n\nregistry = ToolRegistry()\nregistry.register(CodeExecutorTool())\nregistry.register(FileReaderTool())\n\nagent = TaskAgent(\n    llm=llm,\n    memory=memory,\n    tool_registry=registry,\n    system_prompt=\"你是一个可以使用工具的助手。\",\n    max_tool_rounds=5,\n)\n\nresponse = await agent.chat(\"帮我计算第 20 个斐波那契数\", session_id=\"task_1\")\nprint(response.content)\nprint(response.tool_calls)\n```\n\n---\n\n## Tools 工具系统\n\n工具需要继承 `Tool`，并声明 Function Calling schema。\n\n```python\nfrom tools import Tool, ToolRegistry, ToolResult\n\n\nclass WeatherTool(Tool):\n    name = \"get_weather\"\n    description = \"查询城市天气\"\n    parameters = {\n        \"type\": \"object\",\n        \"properties\": {\n            \"city\": {\"type\": \"string\", \"description\": \"城市名称\"},\n        },\n        \"required\": [\"city\"],\n    }\n\n    async def execute(self, city: str) -> ToolResult:\n        return ToolResult(\n            success=True,\n            output={\"city\": city, \"weather\": \"sunny\"},\n        )\n\n\nregistry = ToolRegistry()\nregistry.register(WeatherTool())\n```\n\n`ToolRegistry` 提供：\n\n- `register(tool)`：注册工具实例或工具类\n- `get_function_schemas()`：生成模型可识别的工具 schema\n- `call(name, **kwargs)`：按名称执行工具\n- `call_from_llm_response(tool_call)`：从模型返回的 tool_call 执行工具\n\n内置工具：\n\n- `WebSearchTool`：搜索工具示例桩，实际项目需接 SerpAPI、Bing Search 等真实搜索 API\n- `FileReaderTool`：读取本地文本文件\n- `CodeExecutorTool`：执行 Python 代码片段\n\n注意：`CodeExecutorTool` 当前是模板级示例实现，生产环境应替换为 Docker、微服务沙箱或其他隔离执行环境。\n\n---\n\n## Skills 技能系统\n\nSkill 是“代码直接调用的 LLM 能力单元”，区别于由模型自动触发的 Tool。\n\n内置 Skill：\n\n- `JsonExtractorSkill`：从文本中提取 JSON，支持 Markdown 代码块、前后缀文本、尾随逗号\n- `DocumentParserSkill`：从非结构化文本提取结构化字段\n- `ReportGeneratorSkill`：基于模板生成报告\n\n使用示例：\n\n```python\nfrom skills import JsonExtractorSkill\n\nskill = JsonExtractorSkill(llm)\ndata = await skill.run('用户说: {\"name\": \"张三\", \"age\": 25}')\nprint(data)\n```\n\n自定义 Skill：\n\n```python\nfrom skills import Skill\n\n\nclass SummarySkill(Skill):\n    name = \"summary\"\n    description = \"文本摘要\"\n    system_prompt = \"你是一个摘要专家。\"\n\n    async def run(self, text: str) -> str:\n        response = await self.call_llm(f\"请总结以下内容：\\n{text}\")\n        return response.content\n```\n\n---\n\n## RAG 检索增强\n\n当前 RAG 层包括：\n\n- `EmbeddingModel`：按 provider 创建 `DashScopeEmbedding` 或 `OpenAIEmbedding`\n- `QdrantVectorStore`：Qdrant 向量存储\n- `Retriever`：标准向量召回封装\n- `KeywordRetriever`：轻量关键词召回，不依赖外部服务\n- `RetrieverRoute`：描述一条检索路线\n- `MultiRouteRetriever`：多路召回 + RRF 融合排序\n\n### 基础向量检索\n\n```python\nfrom rag import EmbeddingModel, QdrantVectorStore, Retriever\n\nembedding = EmbeddingModel(\n    provider=\"dashscope\",\n    model=\"text-embedding-v3\",\n    api_key=\"sk-xxx\",\n)\n\nvector_store = QdrantVectorStore(\n    collection_name=\"docs\",\n    embedding=embedding,\n    host=\"localhost\",\n    port=6333,\n    dimension=1024,\n)\n\nawait vector_store.add_texts(\n    texts=[\"FastAPI 是一个现代化的 Python Web 框架。\"],\n    metadatas=[{\"source\": \"fastapi_docs\"}],\n)\n\nretriever = Retriever(vector_store=vector_store, top_k=5)\ndocs = await retriever.retrieve(\"FastAPI 是什么？\")\ncontext = Retriever.format_context(docs)\n```\n\n### 多路召回\n\n多路召回适合处理：\n\n- 向量检索漏掉专有名词、编号、短关键词\n- 同时查询多个知识源或多个 collection\n- 把向量召回、关键词召回、业务过滤召回融合排序\n\n```python\nfrom rag import KeywordRetriever, MultiRouteRetriever, RetrieverRoute\n\nvector_retriever = Retriever(vector_store=vector_store, top_k=5)\nkeyword_retriever = KeywordRetriever(\n    documents=[\n        {\n            \"content\": \"FastAPI 基于 Starlette 和 Pydantic。\",\n            \"metadata\": {\"source\": \"fastapi_docs\"},\n        }\n    ],\n    top_k=5,\n)\n\nretriever = MultiRouteRetriever(\n    routes=[\n        RetrieverRoute(\"vector\", vector_retriever, weight=1.0),\n        RetrieverRoute(\"keyword\", keyword_retriever, weight=0.6),\n    ],\n    top_k=5,\n)\n\ndocs = await retriever.retrieve(\"FastAPI Pydantic\")\n```\n\n`MultiRouteRetriever` 会并发执行每条路线，然后用 Reciprocal Rank Fusion 合并排序。融合后的文档 metadata 中会包含 `retrieval_routes` 和 `raw_scores`，Trace 中也会记录这些信息。\n\n### 运行 RAG 示例\n\n```bash\npython -m examples.rag_example\n```\n\n该示例需要本地或远程 Qdrant 可用，并配置 Embedding API Key。\n\n---\n\n## Memory 对话记忆\n\n### LocalMemory\n\n适合开发调试和单进程小应用，进程重启后记忆丢失。\n\n```python\nfrom memory import LocalMemory\n\nmemory = LocalMemory(max_history=20)\n```\n\n### RedisMemory\n\n适合多进程、多实例和需要 TTL 的生产场景。\n\n```python\nfrom memory import RedisMemory\n\nmemory = RedisMemory(\n    redis_url=\"redis:\u002F\u002Flocalhost:6379\u002F0\",\n    max_history=20,\n    ttl_seconds=86400,\n    redis_prefix=\"agent:memory:\",\n)\n```\n\n---\n\n## LangGraph 编排示例\n\n示例文件：\n\n```text\nexamples\u002Flanggraph_orchestration_example.py\n```\n\n图流程：\n\n```text\nSTART\n  -> retrieve\n  -> plan\n  -> 条件判断 need_tool\n      -> tool\n      -> answer\n  -> END\n```\n\n节点说明：\n\n- `retrieve`：使用 RAG 检索上下文\n- `plan`：让 LLM 输出 JSON，判断是否需要工具\n- `tool`：通过 `ToolRegistry` 执行工具\n- `answer`：结合检索上下文和工具结果生成最终回答\n\n运行：\n\n```bash\npython -m examples.langgraph_orchestration_example\n```\n\n这个示例使用 `StateGraph` 显式描述节点和边，适合扩展为审批流、任务拆解流、多 Agent 协作流、带人工确认的流程等。\n\n---\n\n## 执行过程复盘 Trace\n\n模板默认开启轻量 Trace，写入：\n\n```text\ntraces\u002Fagent_runs.jsonl\n```\n\n每次 `ChatAgent`、`TaskAgent`、LangGraph 示例运行都会生成 `trace_id`，并记录：\n\n- `run_start`：请求入口、session、用户输入\n- `rag_retrieve`：召回文档、分数、metadata、多路召回路线信息\n- `memory_load` \u002F `memory_save`：会话记忆读取和写入\n- `tools_available`：当前可用工具 schema\n- `llm_request`：模型、messages、tools schema\n- `llm_response`：模型输出、tool_calls、finish_reason、token 用量\n- `tool_request` \u002F `tool_response`：工具名、参数、结果、错误、耗时\n- `tool_round_limit_reached`：工具轮次达到上限\n- `run_error`：异常类型和错误信息\n- `run_end`：最终响应、总耗时\n\nFastAPI `\u002Fchat` 会返回 `trace_id`：\n\n```json\n{\n  \"reply\": \"...\",\n  \"session_id\": \"test\",\n  \"trace_id\": \"...\"\n}\n```\n\n常用环境变量：\n\n```bash\n# 开关，默认 true\nAGENT_TRACE_ENABLED=true\n\n# Trace 文件路径\nAGENT_TRACE_FILE=traces\u002Fagent_runs.jsonl\n\n# 单个字段最大记录长度，默认 12000\nAGENT_TRACE_MAX_CHARS=12000\n```\n\n查看最近一条 Trace：\n\n```bash\ntail -n 1 traces\u002Fagent_runs.jsonl\n```\n\n注意：Trace 会记录完整 prompt、工具参数和工具输出。生产环境包含敏感数据时，建议在业务层脱敏，或关闭完整 Trace。\n\n---\n\n## FastAPI 接口\n\n### `GET \u002Fhealth`\n\n返回服务状态：\n\n```json\n{\n  \"status\": \"ok\",\n  \"version\": \"1.0.0\"\n}\n```\n\n### `POST \u002Fchat`\n\n请求：\n\n```json\n{\n  \"message\": \"你好\",\n  \"session_id\": \"test\"\n}\n```\n\n响应：\n\n```json\n{\n  \"reply\": \"...\",\n  \"session_id\": \"test\",\n  \"trace_id\": \"...\"\n}\n```\n\n### `POST \u002Fswitch_model`\n\n运行时切换当前全局 Agent 使用的模型。\n\n参数：\n\n- `provider`\n- `model`\n- `api_key`\n- `base_url`\n\n---\n\n## 示例命令\n\n```bash\n# 基础对话\npython -m examples.chat_example\n\n# 工具调用\npython -m examples.tool_agent_example\n\n# 模型切换\npython -m examples.model_switch_example\n\n# RAG 多路召回\npython -m examples.rag_example\n\n# 多 Agent 协作\npython -m examples.multi_agent_example\n\n# LangGraph 编排\npython -m examples.langgraph_orchestration_example\n```\n\n---\n\n## 扩展指南\n\n### 添加新的 LLM Provider\n\n1. 在 `llm\u002F` 下新增实现文件，继承 `LLMBase`\n2. 实现 `generate()` 和 `stream()`\n3. 通过 `register_provider(name, cls)` 注册\n\n### 添加新的 Tool\n\n1. 继承 `Tool`\n2. 定义 `name`、`description`、`parameters`\n3. 实现 `execute()`\n4. 注册到 `ToolRegistry`\n\n### 添加新的 Skill\n\n1. 继承 `Skill`\n2. 实现 `run()`\n3. 通过 `self.call_llm(...)` 复用模型调用逻辑\n\n### 添加新的 Memory 后端\n\n1. 继承 `MemoryBase`\n2. 实现 `add()`、`get_history()`、`clear()`\n3. 在业务初始化时注入到 Agent\n\n### 添加新的 RAG 路线\n\n1. 实现一个带 `retrieve(query, top_k, filter)` 方法的检索器\n2. 用 `RetrieverRoute(name, retriever, weight)` 包装\n3. 加入 `MultiRouteRetriever(routes=[...])`\n\n---\n\n## 生产化注意事项\n\n- `WebSearchTool` 当前是示例桩，需要替换为真实搜索 API。\n- `CodeExecutorTool` 当前直接执行 Python 代码，生产环境必须使用隔离沙箱。\n- Trace 会写入完整 prompt 和工具输出，涉及隐私或密钥时需要脱敏。\n- LocalMemory 不适合多实例部署，生产建议使用 RedisMemory。\n- RAG 生产环境需要为文档分块、去重、增量更新、召回评估和 rerank 继续补齐。\n- `\u002Fswitch_model` 会接收明文 `api_key`，生产环境建议改为受控配置或密钥管理。\n","这是一个开箱即用的现代化AI Agent项目模板，采用Python编写，专为快速构建企业级AI应用而设计。该项目通过分层架构实现了LLM多模型抽象、工具链系统、技能系统、RAG检索增强、记忆系统等核心功能，并支持多Agent编排。技术特点包括统一的多模型接口封装（兼容DashScope和OpenAI）、基于Function Calling的工具调用机制、Qdrant向量检索与RRF融合排序、以及本地内存和Redis滑动窗口记忆管理。此外，还提供了LangGraph编排示例及完整执行过程Trace复盘能力，方便开发者进行调试与评估。此模板适用于需要构建复杂对话系统、任务处理或信息检索场景的企业和个人开发者。",2,"2026-06-11 02:48:58","CREATED_QUERY"]