🧰 AI Agent 服务工具包

一个用于运行 AI 代理服务的完整工具包，基于 LangGraph、FastAPI 和 Streamlit 构建。

它包含一个 LangGraph 代理，一个用于托管它的 FastAPI 服务，一个用于与服务交互的客户端，以及一个使用客户端提供聊天界面的 Streamlit 应用。数据结构和设置基于 Pydantic 构建。

本项目为您提供了一个模板，让您能够轻松构建和运行自己的代理，使用 LangGraph 框架。它展示了从代理定义到用户界面的完整设置，通过提供一个全面、强大的工具包，使开始基于 LangGraph 的项目变得更加容易。

🎥 观看仓库和应用的视频指南

概述

尝试应用！

快速开始

直接在 Python 中运行

# 至少需要一个大语言模型 (LLM) API 密钥
echo 'OPENAI_API_KEY=your_openai_api_key' >> .env

# uv 是安装 agent-service-toolkit 的推荐方式，但 "pip install ." 也可以工作
# 关于 uv 安装选项，请参见：https://docs.astral.sh/uv/getting-started/installation/
curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh

# 安装依赖。"uv sync" 会自动创建 .venv
uv sync --frozen
source .venv/bin/activate
python src/run_service.py

# 在另一个终端窗口中
source .venv/bin/activate
streamlit run src/streamlit_app.py

使用 Docker 运行

echo 'OPENAI_API_KEY=your_openai_api_key' >> .env
docker compose watch

架构图

主要功能

1. LangGraph 代理及最新特性：使用 LangGraph 框架构建的自定义代理。实现了最新的 LangGraph v1.0 特性，包括带有 interrupt() 的人机协作循环、带有 Command 的流程控制、带有 Store 的长期记忆，以及 langgraph-supervisor。
2. FastAPI 服务：提供流式和非流式端点来托管代理。
3. 高级流式传输：一种新颖的方法以支持基于 token 和基于消息的流式传输。
4. Streamlit 界面：提供用户友好的聊天界面以与代理交互，包括语音输入和输出。
5. 多代理支持：在服务中运行多个代理并通过 URL 路径调用。可用代理和模型描述在 /info 中。
6. 异步设计：利用 async/await 高效处理并发请求。
7. 内容审核：实现 Safeguard 进行内容审核（需要 Groq API 密钥）。
8. 检索增强生成 (RAG) 代理：使用 ChromaDB 的基本 RAG 代理实现 - 见 文档。
9. 反馈机制：包含集成 LangSmith 的基于星级的反馈系统。
10. Docker 支持：包含 Dockerfile 和 docker compose 文件，便于开发和部署。
11. 测试：包含针对整个仓库的稳健单元测试和集成测试。

关键文件

仓库结构如下：

• src/agents/: 定义具有不同能力的多个代理
• src/schema/: 定义协议模式
• src/core/: 核心模块，包括大语言模型 (LLM) 定义和设置
• src/service/service.py: 用于托管代理的 FastAPI 服务
• src/client/client.py: 用于与代理服务交互的客户端
• src/streamlit_app.py: 提供聊天界面的 Streamlit 应用
• tests/: 单元测试和集成测试

设置与使用

1. 克隆仓库：

   git clone https://github.com/JoshuaC215/agent-service-toolkit.git
   cd agent-service-toolkit
   

2. 设置环境变量： 在根目录创建 .env 文件。至少需要一个大语言模型 (LLM) API 密钥或配置。查看 .env.example 文件 以获取可用环境变量的完整列表，包括各种模型提供商 API 密钥、基于头的认证、LangSmith 追踪、测试和开发模式以及 OpenWeatherMap API 密钥。

3. 现在您可以在本地运行代理服务和 Streamlit 应用，使用 Docker 或仅使用 Python。推荐 Docker 设置，因为它可以简化环境设置，并在您修改代码时立即重新加载服务。

特定 AI 提供商的额外设置

• 设置 Ollama
• 设置 VertexAI
• 使用 ChromaDB 设置 RAG

构建或自定义您的代理

为了根据您的用例自定义代理：

1. 将新代理添加到 src/agents 目录。您可以复制 research_assistant.py 或 chatbot.py 并修改它以更改代理的行为和工具。
2. 导入并将新代理添加到 src/agents/agents.py 中的 agents 字典。您的代理可以通过 /<your_agent_name>/invoke 或 /<your_agent_name>/stream 调用。
3. 调整 src/streamlit_app.py 中的 Streamlit 界面以匹配您的代理能力。

处理私有凭证文件

如果您的代理或所选大语言模型 (LLM) 需要基于文件的凭证文件或证书，已提供 privatecredentials/ 以供您的开发便利。除 .gitkeep 文件外，所有内容都被 git 和 docker 的构建过程忽略。请参阅 使用基于文件的凭证 了解建议用法。

Docker 配置

本项目包含一个 Docker 配置，用于方便的开发和部署。compose.yaml 文件定义了三个服务：postgres、agent_service 和 streamlit_app。每个服务的 Dockerfile 位于其各自的目录中。

对于本地开发，我们推荐使用 docker compose watch（一种文件监听功能）。此功能通过在检测到源代码更改时自动更新容器，提供更流畅的开发体验。

1. 确保您的系统已安装 Docker 和 Docker Compose (>= v2.23.0)。

2. 从 .env.example 创建 .env 文件。至少需要提供 LLM（大型语言模型）API 密钥（例如 OPENAI_API_KEY）。

   cp .env.example .env
   # Edit .env to add your API keys
   

3. 以监听模式构建并启动服务：

   docker compose watch
   

   这将自动执行以下操作：

   • 启动 PostgreSQL 数据库服务，代理服务将连接到此服务
   • 使用 FastAPI 启动代理服务
   • 启动用于用户界面的 Streamlit 应用

4. 现在，当您修改代码时，服务将自动更新：

   • 相关 python 文件和目录中的更改将触发相关服务的更新。
   • 注意：如果您修改了 pyproject.toml 或 uv.lock 文件，则需要通过运行 docker compose up --build 重新构建服务。

5. 在 Web 浏览器中导航至 http://localhost:8501 即可访问 Streamlit 应用。

6. 代理服务 API 将在 http://0.0.0.0:8080 可用。您还可以在 http://0.0.0.0:8080/redoc 使用 OpenAPI 文档。

7. 使用 docker compose down 停止服务。

此设置允许您实时开发和测试更改，而无需手动重启服务。

基于 AgentClient 构建其他应用

仓库包含一个通用的 src/client/client.AgentClient（代理客户端），可用于与代理服务交互。此客户端设计灵活，可用于在代理之上构建其他应用。它支持同步和异步调用，以及流式和非流式请求。

请参阅 src/run_client.py 文件以获取如何使用 AgentClient 的完整示例。快速示例如下：

from client import AgentClient
client = AgentClient()

response = client.invoke("Tell me a brief joke?")
response.pretty_print()
# ================================== Ai Message ==================================
#
# A man walked into a library and asked the librarian, "Do you have any books on Pavlov's dogs and Schrödinger's cat?"
# The librarian replied, "It rings a bell, but I'm not sure if it's here or not."

使用 LangGraph Studio 进行开发

该代理支持 LangGraph Studio，这是为 LangGraph 开发代理的集成开发环境（IDE）。

langgraph-cli[inmem] 随 uv sync 一起安装。您可以按照上述描述将 .env 文件添加到根目录，然后使用 langgraph dev 启动 LangGraph Studio。根据需要自定义 langgraph.json。请参阅 本地快速入门 了解更多。

不使用 Docker 的本地开发

您也可以在不使用 Docker 的情况下，仅使用 Python 虚拟环境在本地运行代理服务和 Streamlit 应用。

1. 创建虚拟环境并安装依赖项：

   uv sync --frozen
   source .venv/bin/activate
   

2. 运行 FastAPI 服务器：

   python src/run_service.py
   

3. 在单独的终端中运行 Streamlit 应用：

   streamlit run src/streamlit_app.py
   

4. 打开浏览器并导航到 Streamlit 提供的 URL（通常是 http://localhost:8501）。

使用或受 agent-service-toolkit 启发的项目

以下是几个从本仓库获取代码或灵感的一些公开项目。

• PolyRAG - 扩展了 agent-service-toolkit，使其具备对 PostgreSQL 数据库和 PDF 文档的 RAG 能力。
• alexrisch/agent-web-kit - agent-service-toolkit 的 Next.JS 前端
• raushan-in/dapa - 数字逮捕保护应用 (DAPA) 允许用户通过用户友好的平台高效地报告金融诈骗和欺诈行为。

请创建拉取请求编辑 README 或发起讨论以添加任何新项目！我们很乐意纳入更多项目。

贡献

欢迎贡献！请随时提交拉取请求。目前，测试需要使用不使用 Docker 配置的本地开发环境运行。要运行代理服务的测试：

1. 确保您处于项目根目录并已激活虚拟环境。

2. 安装开发依赖项和 pre-commit 钩子：

   uv sync --frozen
   pre-commit install
   

3. 使用 pytest（测试框架）运行测试：

   pytest
   

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

agent-service-toolkit 快速上手指南

agent-service-toolkit 是一个基于 LangGraph、FastAPI 和 Streamlit 构建的完整 AI Agent 服务工具包。它提供了从 Agent 定义到用户界面的全套解决方案，支持流式响应、多 Agent 管理及 Docker 部署。

1. 环境准备

• 操作系统: Linux / macOS / Windows (WSL)
• Python 版本: 3.10+
• 依赖工具:
  • git: 用于克隆仓库
  • uv (推荐): 高性能 Python 包管理工具（见安装步骤）
  • docker & docker-compose (可选): 用于容器化运行
• 网络建议: 国内开发者若遇到拉取速度较慢，可配置 Git 代理或镜像源加速。

2. 安装步骤

方式一：本地 Python 环境运行

1. 克隆仓库

   git clone https://github.com/JoshuaC215/agent-service-toolkit.git
   cd agent-service-toolkit
   

2. 安装 uv (如未安装)

   curl -LsSf https://astral.sh/uv/0.7.19/install.sh | sh
   

3. 配置环境变量 创建 .env 文件并填入至少一个 LLM API Key（例如 OpenAI）：

   echo 'OPENAI_API_KEY=your_openai_api_key' >> .env
   

   提示：更多配置项请参考根目录下的 .env.example 文件。

4. 同步依赖

   uv sync --frozen
   source .venv/bin/activate
   

方式二：Docker 容器运行 (推荐)

1. 配置环境变量

   cp .env.example .env
   # 编辑 .env 文件添加 API Key
   

2. 启动服务 使用 docker compose watch 实现代码热更新：

   docker compose watch
   

3. 基本使用

启动服务与界面

如果你选择了本地 Python 环境，需要在两个终端窗口分别执行以下命令：

终端 1 (启动后端服务):

source .venv/bin/activate
python src/run_service.py

终端 2 (启动前端界面):

source .venv/bin/activate
streamlit run src/streamlit_app.py

访问应用

• Web 界面: 打开浏览器访问 http://localhost:8501
• API 接口: 后端服务运行在 http://0.0.0.0:8080，文档地址为 http://0.0.0.0:8080/redoc

客户端调用示例

项目内置了 AgentClient，可用于构建其他应用：

from client import AgentClient
client = AgentClient()

response = client.invoke("Tell me a brief joke?")
response.pretty_print()

自定义 Agent

如需添加自己的 Agent：

1. 在 src/agents/ 目录下新建文件。
2. 在 src/agents/agents.py 中注册新 Agent。
3. 调整 src/streamlit_app.py 以适配新 Agent 的功能。