agent-service-toolkit

环境要求

• Python 环境（本地运行方式需 Python 虚拟环境）
• 推荐安装 uv 依赖管理工具，pip install . 亦可
• Docker 与 Docker Compose v2.23.0 及以上（Docker 方式）
• 至少一个 LLM 模型提供商的 API Key

安装与启动步骤

1. 1克隆代码仓库

   把项目源码下载到本地并进入项目根目录，后续所有命令都在该目录执行。

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

   复制

2. 2准备环境变量

   从示例文件复制出 .env，然后编辑它填入至少一个 LLM API Key，否则服务无法调用模型。

   cp .env.example .env

   复制

3. 3安装 uv 工具

   README 推荐用 uv 安装依赖；若已装过可跳过，也可直接用 pip install . 替代。

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

   复制

4. 4安装项目依赖

   uv sync 会自动创建 .venv 虚拟环境并安装全部依赖，随后激活该虚拟环境。

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

   复制

5. 5启动 Agent 服务

   运行 FastAPI 服务端，保持该终端窗口不要关闭；接口将监听 8080 端口。

   python src/run_service.py

   复制

6. 6启动聊天界面

   另开一个终端激活同一虚拟环境后运行 Streamlit 应用，即可获得聊天 UI。

   streamlit run src/streamlit_app.py

   复制

7. 7Docker 一键启动

   按 README 推荐方式，用 watch 模式同时拉起 postgres、agent_service 与 streamlit_app 三个服务。

   docker compose watch

   复制

关键配置

如何确认成功

浏览器访问 http://localhost:8501 能看到聊天界面，API 文档 http://0.0.0.0:8080/redoc 可正常打开。

常见问题

注意事项

• Docker 方式要求 Docker Compose 版本不低于 v2.23.0。
• 暂不支持 uv 时可用 pip install . 安装依赖，README 明确说明同样可行。
• 停止 Docker 服务使用 docker compose down。
• .env.example 中还有更多环境变量（认证、LangSmith 追踪等）可参考其注释配置。