oTTomator 样板 Python Agent 实战指南基于 FastAPI 构建 Live Agent Studio 双存储后端Supabase / PostgreSQL智能体【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents导读本文以 oTTomator 仓库中的~sample-python-agent~样板项目为核心完整讲解如何用 FastAPI 搭建一个符合 Live Agent Studio 平台规范的 Python Agent。该样板同时提供了 Supabase 与原生 PostgreSQLasyncpg两个存储后端实现是接入对话历史持久化、Bearer Token 认证与异步 API 处理的最简参考模板。读完本文你将掌握从环境配置、建表、Docker/本地双方式部署到发起首个 curl 请求、以及在其 TODO 区段接入任意 LLM 逻辑的完整开发闭环。一、项目定位Live Agent Studio 的 Python Agent 最小参考实现Live Agent StudiooTTomator 社区驱动的开源 Agent 平台要求所有 Python 版 Agent 遵循统一的服务契约HTTP 接口、会话化对话存储、Bearer Token 鉴权。~sample-python-agent~目录下的样板正是为满足这一契约而设计的最小可运行骨架其能力边界覆盖处理自然语言查询以query字段进入按session_id维护并回溯会话历史预留 AI 模型接入位OpenAI、Anthropic、自研模型等均可在 TODO 区扩展会话数据的存取与持久化基于环境变量的鉴权与安全控制。样板提供两个等价变体可依据数据层选型自由切换变体文件数据库访问方式核心依赖Supabase 版sample_supabase_agent.pySupabase Python SDKcreate_clientsupabasePostgreSQL 版sample_postgres_agent.py原生asyncpg连接池asyncpg两个文件在请求/响应模型、鉴权逻辑、会话历史读写上结构完全对称差异仅体现在数据访问层这种逻辑与存储解耦的设计非常适合作为多后端模板。二、环境前置条件Python 3.11 及以上base_python_docker/Dockerfile 采用python:3.11-slim作为基础镜像pip包管理器PostgreSQL 数据库或 Supabase 账号二选一建议具备 FastAPI 与异步 Python、RESTful API、Pydantic 模型、环境变量、PostgreSQL 的基础认知。依赖清单见 requirements.txt共六项fastapi、uvicorn、pydantic、supabase、python-dotenv、asyncpg。其中python-dotenv用于加载.envasyncpg仅 PostgreSQL 版实际使用但保留在统一依赖中以保持两种部署方式切换的平滑性。三、核心组件与源码级拆解3.1 FastAPI 应用骨架两个文件都以app FastAPI()初始化并注册HTTPBearer安全方案与全开放 CORS 中间件allow_origins[*]。PostgreSQL 版额外通过lifespan上下文管理器管理连接池生命周期——启动时asyncpg.create_pool(os.getenv(DATABASE_URL))创建连接池关闭时统一释放避免每次请求新建数据库连接的开销见 sample_postgres_agent.py。3.2 数据模型Pydantic请求模型AgentRequest定义四个必填字段这也是 Live Agent Studio 平台注入请求时的标准契约class AgentRequest(BaseModel): query: str # 用户输入文本 user_id: str # 用户唯一标识 request_id: str # 本次请求唯一标识用于追踪/日志 session_id: str # 当前会话 ID对话分组的键响应模型AgentResponse仅含success: bool用于指示本次处理是否成功class AgentResponse(BaseModel): success: bool3.3 鉴权机制Bearer Token 校验verify_token函数sample_supabase_agent.py是安全核心行为可精确概括为从环境变量读取API_BEARER_TOKEN若该变量未设置返回500配置缺失是服务端问题若请求携带的 token 与期望值不一致返回401校验通过后注入端点依赖authenticated: bool Depends(verify_token)。def verify_token(credentials: HTTPAuthorizationCredentials Security(security)) - bool: expected_token os.getenv(API_BEARER_TOKEN) if not expected_token: raise HTTPException(status_code500, detailAPI_BEARER_TOKEN environment variable not set) if credentials.credentials ! expected_token: raise HTTPException(status_code401, detailInvalid authentication token) return True3.4 会话历史读写fetch_conversation_history(session_id, limit10)按session_id查询messages表以created_at倒序取最近 10 条再[::-1]反转成时间正序供 LLM 作为上下文使用。Supabase 版使用链式查询.eq(session_id, ...).order(created_at, descTrue).limit(limit)Postgres 版使用带$1/$2参数的预编译 SQL天然防注入。store_message(session_id, message_type, content, dataNone)将消息包装为{type: ..., content: ..., data: ...}的 JSONB 结构写入数据库。type字段为human用户或ai/assistant模型回复data可选用于附加request_id、错误信息等元数据。两处数据库异常都会被捕获并转为HTTPException(status_code500)保证服务不会因单条读写失败而崩溃。3.5 数据库 SchemaSupabase 与 PostgreSQL 使用同一张messages表结构-- 启用 pgcrypto 扩展以支持 UUID 生成 CREATE EXTENSION IF NOT EXISTS pgcrypto; CREATE TABLE messages ( id uuid DEFAULT gen_random_uuid() PRIMARY KEY, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, session_id TEXT NOT NULL, message JSONB NOT NULL ); CREATE INDEX idx_messages_session_id ON messages(session_id); CREATE INDEX idx_messages_created_at ON messages(created_at);message列的 JSONB 内部结构为{ type: human | ai | assistant, content: 消息正文, data: { request_id: ..., error: ... } }注意Supabase 默认已启用pgcrypto无需手动执行扩展创建语句自建 PostgreSQL 则必须执行。四、环境配置.env 详解4.1 克隆仓库与准备 .envgit clone https://gitcode.com/GitHub_Trending/ot/ottomator-agents.git cd ottomator-agents/~sample-python-agent~ # 复制示例环境文件 cp .env.example .env # 编辑 .env 填入你的凭据 nano .env仓库已内置 .env.example 模板各变量注释完整变量适用版本说明SUPABASE_URLSupabase项目 API 设置页中的 Project URLSUPABASE_SERVICE_KEYSupabase即 API 设置页中的service_rolesecret注意其绕过 RLS 的权限级别DATABASE_URLPostgreSQL连接串格式见下文API_BEARER_TOKEN两个版本自定义 Bearer Token部署到 Studio 后由平台托管替换DATABASE_URL标准格式postgresql://[user]:[password][host]:[port]/[database_name]示例postgresql://postgres:mypasswordlocalhost:5432/mydb若使用 Supabase 的 Postgres 直连可在 Database 设置 → Connection string → URI 中获取。⚠️Docker 环境特别提醒环境变量值不要加引号包裹即使包含特殊字符也交由 Docker 自行处理加引号反而会被当成字面量解析。五、安装与部署Docker 与本地双路径5.1 Docker 安装推荐采用两级镜像策略先构建共享基础镜像base_python_docker再构建具体 Agent 镜像便于多个 Agent 复用同一 Python 3.11 依赖环境。# 1. 构建基础镜像确保 Docker 已启动 cd ../base_python_docker docker build -t ottomator/base-python:latest . cd ../~sample-python-agent~ # 2. 构建 Agent 镜像可在 Dockerfile 中切换 Supabase/PostgreSQL 版本 docker build -t sample-python-agent . # 3. 运行容器 docker run -d --name sample-python-agent -p 8001:8001 --env-file .env sample-python-agent容器启动后服务监听于http://localhost:8001。基础镜像的安全细节可参考 base_python_docker/Dockerfile创建非 root 用户appuser并以该用户运行规避容器内提权风险。Agent 侧 Dockerfile 支持通过构建参数自定义端口且默认启动命令为uvicorn sample_supabase_agent:app --host 0.0.0.0 --port ${PORT}注释中明确提示可改为sample_postgres_agentFROM ottomator/base-python:latest ARG PORT8001 ENV PORT${PORT} WORKDIR /app COPY . . EXPOSE ${PORT} CMD [sh, -c, uvicorn sample_supabase_agent:app --host 0.0.0.0 --port ${PORT}]5.2 本地安装免 Docker 替代方案# 1. 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Windows 下: venv\Scripts\activate # 2. 安装依赖 pip install -r requirements.txt # 3. 启动按需选择版本 uvicorn sample_supabase_agent:app --host 0.0.0.0 --port 8001 uvicorn sample_postgres_agent:app --host 0.0.0.0 --port 8001两个文件末尾均包含if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8001)因此也可直接python sample_supabase_agent.py启动。六、发起第一个请求使用 curl 或任意 HTTP 客户端验证 Agent 是否就绪。注意Authorization头必须携带.env中API_BEARER_TOKEN的精确值。Supabase 版curl -X POST http://localhost:8001/api/sample-supabase-agent \ -H Authorization: Bearer your-token-here \ -H Content-Type: application/json \ -d { query: Hello, agent!, user_id: test-user, request_id: test-request-1, session_id: test-session-1 }PostgreSQL 版curl -X POST http://localhost:8001/api/sample-postgres-agent \ -H Authorization: Bearer your-token-here \ -H Content-Type: application/json \ -d { query: Hello, agent!, user_id: test-user, request_id: test-request-1, session_id: test-session-1 }成功时返回{success: true}同时messages表中会依次落库一条type: human的用户消息和一条type: ai/assistant的样板回复回复内容带data.request_id便于追踪。七、定制你自己的 AgentTODO 区段接入指南样板的端点逻辑sample_supabase_agent.py完整展示了平台 Agent 的标准处理管线其顺序为读取会话历史 → 转为role/content消息列表 → 持久化用户查询 → 调用自定义 Agent 逻辑 → 持久化回复 → 返回成功。源码中的 TODO 块就是你插入业务逻辑的落点并明确给出三个关键输入约定使用messages数组作为聊天历史不含用户最新一条使用request.query作为本次用户提示词使用request.session_id在 Agent 执行过程中向数据库追加更多状态消息。7.1 接入 AI 模型的参考骨架# Example: Add AI model integration async def get_ai_response(query: str, history: List[Dict]) - str: # 在这里接入你的 AI 模型逻辑OpenAI、Anthropic 或自定义模型 return AI response app.post(/api/your-agent, response_modelAgentResponse) async def your_agent(request: AgentRequest): # 获取会话历史 history await fetch_conversation_history(request.session_id) # 使用你的 AI 模型处理 response await get_ai_response(request.query, history) # 存储回复 await store_message( session_idrequest.session_id, message_typeassistant, contentresponse ) return AgentResponse(successTrue)源码注释还提示不同的 Agent 框架Pydantic AI、LangChain 等只需调整历史转messages这一段{role: msg_type, content: msg_content}其余管道可原样复用。7.2 定制步骤清单Fork 模板复制样板目录按需重命名文件并更新引用路径与端点路由替换 Agent 逻辑在 TODO 区段实现get_ai_response可接入外部 LLM、工具调用、多步推理等追加依赖在 requirements.txt 增加新包并记录外部服务/API 的用法强化错误处理对自定义操作使用 try/except 并抛出带上下文的HTTPException与样板既有的 500 兜底风格保持一致try: result await your_operation() except YourCustomError as e: raise HTTPException( status_code400, detailfOperation failed: {str(e)} )7.3 状态透传能力源码中store_message的data参数支持在 Agent 处理过程中写入中间状态如工具调用进度、检索结果摘要等这些记录会随会话历史一并被后续轮次读取是实现Agent 边执行边汇报模式的底层支撑。八、故障排查速查表症状排查方向401 Authentication 错误核对.env中API_BEARER_TOKEN是否与请求头完全一致含大小写确认 Authorization 头格式为Bearer token500 API_BEARER_TOKEN not set服务端未读取到环境变量检查.env是否位于工作目录且已load_dotenv()Supabase 连接失败验证SUPABASE_URL/SUPABASE_SERVICE_KEY凭据检查messages表权限service_role key 应具备读写权PostgreSQL 连接失败检查DATABASE_URL格式postgresql://[user]:[password][host]:[port]/[database_name]确认数据库用户权限、服务可达性、表是否已按第五节 SQL 创建性能问题检查数据库查询执行计划对高频访问数据考虑缓存PostgreSQL 版可监控asyncpg连接池使用率默认池大小对多数场景合理必要时按负载调整九、平台接入要点该样板是 oTTomator 仓库中 Python Agent 的官方起点主 README.md 在 FAQ 中将其与~sample-n8n-agent~并列为两类 Agent 的开发模板。接入 Live Agent Studio 时需注意平台托管后API_BEARER_TOKEN会被替换为平台下发值请求契约query/user_id/request_id/session_id由平台按上述模型注入因此保持AgentRequest字段不变是兼容平台调度的关键。除本样板外仓库内~sample-python-agent~之外的studio-integration-version类目录如 mcp-agent-army/studio-integration-version展示了同一契约在更复杂 Agent 上的演进形态可作为进阶参考。【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考