5分钟从零到AI Agent服务：agent-service-toolkit实战教程

5分钟从零到AI Agent服务：agent-service-toolkit实战教程

【免费下载链接】agent-service-toolkitFull toolkit for running an AI agent service built with LangGraph, FastAPI and Streamlit项目地址: https://gitcode.com/GitHub_Trending/ag/agent-service-toolkit

刚用 LangGraph 搭好一个智能体，想让别人通过接口调起来，你还得自己补服务层、客户端和界面。agent-service-toolkit 把这条链路做成了可直接运行的模板：核心是 LangGraph，服务层是 FastAPI，界面是 Streamlit，中间还包括对话记忆的存储。本文按这个顺序读：

• 项目概览与能力清单
• 本地或容器两条路径完成首次运行
• 三个与你最相关的核心功能详解
• 实战搭一个自定义智能体，以及部署常见坑

📦 项目概览

它面向用 LangGraph 做智能体开发、但不想自己搭服务层的开发者：你只需提供智能体图定义，它负责 FastAPI 端点、客户端 SDK、Streamlit 聊天界面，以及默认的 PostgreSQL 会话存储，重启后对话历史仍可查询。

能力全景：

• 10个内置智能体模板：chatbot、research-assistant、RAG 助手、supervisor 多智能体等，每个都是可直接运行的样例
• 双重流式输出：/stream端点同时支持 token 级与消息级流式传输
• 多智能体按 URL 路径访问：一个服务起来后，用/{agent_id}/invoke调用不同智能体
• 内容安全过滤：内置 Safeguard 内容审核（需配置 Groq 密钥）
• Docker 热重载开发：docker compose watch自动同步代码改动，无需手动重建

🚀 从零到第一次运行

本地运行

1. 克隆仓库并进入目录：git clone https://gitcode.com/GitHub_Trending/ag/agent-service-toolkit
2. 配置至少一个 LLM 密钥：echo 'OPENAI_API_KEY=your-key' >> .env，完整变量列表见 .env.example
3. 安装依赖：uv sync --frozen，会自动创建.venv虚拟环境（用 pip 也可以）
4. 启动服务：source .venv/bin/activate && python src/run_service.py，FastAPI 监听 8080 端口
5. 另开终端启动界面：streamlit run src/streamlit_app.py，浏览器打开 http://localhost:8501 进入聊天界面

容器化运行

cp .env.example .env # 填入你的 API 密钥 docker compose watch

一条命令同时拉起 postgres、智能体服务、Streamlit 界面三个容器，src/下的代码改动会自动同步并重启服务。

🔍 核心功能详解

目录结构对应它的四层分工：src/agents/放智能体，src/service/是 FastAPI 服务，src/client/是客户端 SDK，src/streamlit_app.py是界面。下面三个功能与你日常使用关系最大。

多智能体注册表：按 URL 路径访问不同智能体

一个服务起来之后，多个智能体怎么区分？src/agents/agents.py 维护一个agents字典作为注册表，key 直接就是 URL 路径：POST /research-assistant/invoke调用研究助手，GET /rag-assistant/threads拉取该智能体的历史会话，GET /info返回全部智能体与模型列表。每个智能体不用单独起服务，Streamlit 界面里也能直接切换。

双重流式：token 级与消息级同时可用

流式响应给前端时，粒度常常是痛点。项目的/stream与/{agent_id}/stream端点同时支持 token 级（逐字渲染）和消息级（完整消息节点）两种流式，前端按需取用。

AgentClient：从自己的代码里调用服务

要把这套服务嵌进你自己的系统，用 src/client/client.py 里的AgentClient，同步 invoke 和异步 stream 都支持：

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

完整用法示例见 src/run_client.py。

🛠️ 实战：搭一个你自己的智能体

以基于 chatbot 模板做一个专属智能体为例，三步完成：

第一步，改什么。复制 src/agents/chatbot.py 为src/agents/my_agent.py，只改系统提示词和工具。

第二步，配什么。在 src/agents/agents.py 中导入并注册：

# src/agents/agents.py from agents.my_agent import my_agent agents = { ... "my-agent": Agent( description="My first custom agent.", graph_like=my_agent, ), }

第三步，怎么验证。重启服务后执行curl http://localhost:8080/info，返回列表中出现my-agent即注册成功；再POST /my-agent/invoke发一条消息实测。

⚙️ 部署、调优与常见坑

• 服务起来但没响应：.env至少要有一个 LLM 密钥；只用本地 Ollama 的话见 docs/Ollama.md
• 依赖改了没生效：docker compose watch只自动同步src/下的代码，改动pyproject.toml或uv.lock后要跑docker compose up --build
• 审核层缺失：Safeguard 内容审核依赖GROQ_API_KEY，不配也能跑，但没有安全过滤
• 对外暴露要认证：在.env配置AUTH_SECRET启用 header 认证，避免 8080 端口裸奔

agent-service-toolkit 把"智能体定义 → 服务暴露 → 界面接入"整条链路压成一套模板，跑通一次之后，你的精力可以全部放在智能体逻辑本身。延伸阅读：README.md、docs/RAG_Assistant.md、src/run_client.py；服务启动后 API 参考在 http://localhost:8080/redoc。

【免费下载链接】agent-service-toolkitFull toolkit for running an AI agent service built with LangGraph, FastAPI and Streamlit项目地址: https://gitcode.com/GitHub_Trending/ag/agent-service-toolkit