AI Agent Service Toolkit
用 LangGraph、FastAPI 和 Streamlit 搭建可自托管的智能体服务。
证据清楚列出模型供应商、LangSmith、GitHub MCP、搜索、天气、数据库及部署等主要数据流，并为文件凭据提供不进入 Git 和 Docker 构建上下文的目录；部署工作流也仅声明 contents: read。依赖采用冻结安装、14 天供应链冷却策略和精确的兼容版本范围，但所给材料不含锁文件、漏洞扫描或依赖审计结果，因此不能满分。README 提到 interrupt() 人工介入，但没有证明所有具有外部副作用的工具在执行前均要求确认；GitHub MCP 工具的权限边界、发送字段和读写行为也未展开。停止容器有说明，但对代理已经产生的远程变更没有通用撤销机制。作者、包元数据和 MIT 版权归属一致且明确，故来源归属满分；发布者未获企业注册验证仅表示身份未经独立确认，不据此作额外扣分。
README、包配置、工作流和所示测试对 Python 版本、代理加载、惰性初始化及无令牌或连接失败时的降级行为基本一致；测试还验证了未加载、代理不存在和图未创建等错误状态。冻结依赖、Docker、多个提供商、SQLite/Postgres/MongoDB 选项及可选端到端冒烟脚本提高了可用性。不过材料只展示测试子集，部分真实基础设施检查不在默认 CI 中，GitHub MCP 连接异常会静默降级为无工具代理，错误是否充分暴露给最终用户也未得到证明，因此各项保留扣分。
项目明确面向希望搭建 LangGraph 服务、API、客户端和聊天界面的开发者，覆盖本地 Python、Docker、LangGraph Studio、多模型供应商、多个代理、RAG 和自定义前端，场景与环境适配说明充分。代理通过命名路径、/info、invoke/stream 端点和惰性加载形成较清楚的触发边界，缺少凭据时 GitHub MCP 工具不会加载。不过不同代理可调用工具的精确权限、输入约束、确认策略以及生产环境安全边界没有在证据中完整枚举，因此能力边界和触发精度未满分。
README 的概览、架构、关键文件、快速开始、Docker/本地安装、客户端示例、定制方法和专项文档入口组织良好；Python 与 Docker 两条安装路径包含具体命令和版本要求。MIT 正文、README 和包分类器一致，许可满分。已说明 Beta 状态、可选集成不进默认 CI、重建条件及单人维护节奏，但没有集中 FAQ，也没有完整汇总生产限制。包版本为 0.1.0，命名总体一致，却未提供变更日志、发布历史或兼容性承诺，所以版本治理较弱。维护责任、响应节奏和维护文档位置明确，尽管发布者身份未经外部验证。
该仓库把代理图、FastAPI 服务、同步/异步客户端、流式协议、Streamlit UI、持久化、Docker 和测试脚手架整合成可直接改造的模板，相比单独的代理示例具有明显增量价值；输出可通过聊天 UI、普通 API、流式 API 和 AG-UI 使用。README 给出了调用示例和访问地址，但没有静态证据证明所有输出的结构、引用、错误呈现或质量控制都达到生产标准。成本方面支持本地 Ollama和选择性冒烟测试，但默认功能集合依赖众多大型包、外部模型密钥、数据库及可选观测服务，且没有资源消耗或费用基准，因此成本收益仅属充分但不全面。
主要主张能够在 README、pyproject、工作流和代理加载测试之间相互对应，例如版本范围、部署链、惰性加载和失败降级都有具体材料支撑。多个来源提供了一定交叉印证，但“full, robust toolkit”“robust unit and integration tests”“latest features”等较强宣传性表述无法由所给测试子集完全验证，徽章也不是修订固定的执行证据。文档会明确区分默认 CI 与可选真实基础设施冒烟检查，并说明 Beta 与维护限制，事实和推断分离尚可；不过部分质量与新颖性主张未附可核对指标，故三项均不满分。
- GitHub MCP 和其他代理工具可能具有远程读写副作用；上线前应逐工具审查权限范围、参数传输、用户确认及审计记录。
- 不要把连接失败后退化为“无工具代理”视为成功；应确认服务和界面会明确告知操作者功能已降级。
- 依赖数量较多，且所给证据不含 uv.lock 或漏洞扫描结果；部署前应在该修订上核验锁文件、传递依赖和镜像漏洞。
- 真实 Postgres、MongoDB、AG-UI 与 LangFuse 检查是可选项而非默认 CI；使用相应集成时应单独运行并保存结果。
- 凭据目录的忽略规则是有益措施，但仍需验证运行时日志、LangSmith/LangFuse 追踪、反馈和模型供应商请求不会泄露敏感内容。
这个 Agent 能做什么，适合哪些场景？
这是一个用于开发和运行 LangGraph 智能体服务的完整 Python 模板，而非单一成品助手。仓库包含多个智能体实现、FastAPI 服务、通用 AgentClient，以及支持文字和语音交互的 Streamlit 聊天界面。服务同时提供流式与非流式调用，并可通过 URL 路径选择不同智能体；每个智能体还会通过 AG-UI 协议开放给兼容前端。其能力示例覆盖人工介入、长期记忆、多智能体监督、内容审核、基于 ChromaDB 的基础 RAG、会话历史和 LangSmith 反馈。用户可以在本地 Python 环境中运行，也可以通过 Docker Compose 启动 PostgreSQL、智能体服务和 Streamlit 应用。
服务从 src/agents/ 加载已注册的智能体，并由 src/service/service.py 中的 FastAPI 应用对外提供调用。客户端可通过 /<agent_name>/invoke 发起普通请求，或通过 /<agent_name>/stream 获取按 token 或消息传输的流式结果；/info 描述可用智能体和模型，/threads 列出某个用户在各智能体中的历史会话。src/client/client.AgentClient 封装同步、异步、流式和非流式访问，src/streamlit_app.py 则用该客户端生成带语音输入输出、历史会话侧栏和星级反馈的聊天界面。仓库还展示 LangGraph 的 interrupt()、Command、Store 和 langgraph-supervisor，用于人工介入、流程控制、长期记忆和多智能体协作。可选实现包括 ChromaDB RAG、需要 Groq API 密钥的 Safeguard 内容审核、AG-UI 端点以及 PostgreSQL 或 MongoDB 检查点后端。
- 正在验证 LangGraph 架构的 Python 团队，可从现成的智能体、HTTP 服务、客户端和聊天界面开始，而不必自行拼装整个服务链路。
- 需要在同一 FastAPI 服务中托管多个智能体的后端开发者，可按 URL 路径调用不同智能体，并通过 /info 暴露可用配置。
- 需要实时响应体验的应用团队，可使用 token 级或消息级流式端点，并通过 AgentClient 构建 Streamlit 之外的前端。
- 开发需要人工审批、长期记忆或监督智能体流程的工程师，可参考 interrupt()、Command、Store 与 langgraph-supervisor 的实现。
- 构建内部知识问答原型的团队，可采用随仓库提供的基础 ChromaDB RAG 智能体，并按文档完成额外配置。
- 希望接入 CopilotKit 等 AG-UI 兼容前端的团队，可使用每个智能体对应的 AG-UI 服务接口。
这个 Agent 有哪些优点和局限？
- 覆盖从 LangGraph 智能体定义、FastAPI 服务、通用客户端到 Streamlit 界面的完整链路，并同时提供流式和非流式访问。
- 展示 interrupt()、Command、Store 和 langgraph-supervisor 等 LangGraph 1.0 功能，适合需要人工介入、流程控制、长期记忆或多智能体监督的项目。
- 每个智能体均提供 AG-UI 协议接口，可连接 CopilotKit 等兼容前端，而 AgentClient 也能支持自建应用。
- 同时支持本地 Python 与 Docker Compose 工作流，并配有单元测试、集成测试和针对可选基础设施的端到端冒烟测试。
- 必须配置至少一个 LLM API 密钥或提供商连接；内容审核还额外需要 Groq API 密钥，部分能力会引入外部服务依赖。
- Docker 工作流会启动 PostgreSQL、FastAPI 服务和 Streamlit 应用，部署复杂度与资源需求高于单进程聊天脚本。
- PostgreSQL、MongoDB、AG-UI 和 LangFuse 的冒烟测试属于手动选择执行的检查，不在默认 CI 中。
- 测试目前要求使用不依赖 Docker 的本地开发环境运行，容器工作流不能替代该测试步骤。
- 项目由单人维护，问题、拉取请求和讨论通常约每两周集中处理一次，非紧急反馈可能需要一到两周。
如何安装或部署这个 Agent？
准备 Python 环境，并至少配置一个 LLM API 密钥或提供商连接参数。快速开始可执行：
git clone https://github.com/JoshuaC215/agent-service-toolkit.git
cd agent-service-toolkit
echo 'OPENAI_API_KEY=your_openai_api_key' >> .env
curl -LsSf https://astral.sh/uv/0.11.32/install.sh | sh
uv sync --frozen
source .venv/bin/activate
python src/run_service.py在另一个终端中执行：
source .venv/bin/activate
streamlit run src/streamlit_app.py也可以先从 .env.example 创建配置，然后执行 docker compose watch；该方式要求 Docker 和 Docker Compose 2.23.0 或更高版本。
如何使用这个 Agent？
服务启动后，在浏览器访问通常位于 http://localhost:8501 的 Streamlit 界面。FastAPI 服务位于 http://0.0.0.0:8080，接口文档可在 http://0.0.0.0:8080/redoc 查看。代码调用示例：
from client import AgentClient
client = AgentClient()
response = client.invoke("Tell me a brief joke?")
response.pretty_print()自定义智能体时，将实现加入 src/agents/，在 src/agents/agents.py 的 agents 字典中注册，然后通过 /<your_agent_name>/invoke 或 /<your_agent_name>/stream 调用；如有需要，再修改 src/streamlit_app.py。开发检查可运行 pytest；涉及 PostgreSQL、MongoDB、AG-UI 或 LangFuse 时，可针对性运行 ./scripts/smoke_test.sh postgres、mongo、agui 或 langfuse。