GenericSuite App MakerGSAMPython FastAPI Agent 实战指南把 AI 应用开发助手接入 oTTomator Live Agent Studio【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文是一份围绕 oTTomator Agents 仓库中 GSAM Python FastAPI Agent 的完整技术指南。它讲解如何基于 Pydantic AI 与 FastAPI 构建一个能生成应用创意、命名、PPT 内容、数据库表定义乃至可运行的 CRUD JSON 与 Python 代码的 AI 开发助手并把它无缝部署到 oTTomator Live Agent Studio 平台。读完本文你将掌握该 Agent 的双数据库变体架构、七类核心工具、环境变量配置、Docker/本地两种部署方式以及完整的请求调试流程。项目概览一个为软件研发流程服务的 AI AgentGSAMGenericSuite App MakerPython FastAPI Agent 是一个面向软件研发全流程的 AI 助手。它允许用户仅通过一段自然语言文本提示即可依次产出创新应用创意生成Innovative App Ideas Generation围绕独特功能、目标受众和潜在用途构思 Web/移动端应用概念应用命名Names Generation为软件应用提出朗朗上口、富有创意的名字建议PowerPoint 内容创作PowerPoint Content Creation起草演示文稿幻灯片内容并为生成配图提供提示词建议应用描述与数据表定义App Description and Table Definitions撰写完整的应用描述与详细的数据库表结构定义CRUD JSON 与 Python 代码生成CRUD JSON and Python Code Generation产出与 GenericSuite 兼容的通用 CRUD 编辑器配置 JSON以及配套的 Python 工具代码。除此之外该 Agent 还具备处理自然语言查询、维护多轮会话历史、对接外部 AI 模型、存取会话数据、处理认证与安全等平台级能力并兼容 oTTomator Live Agent Studio 的接入协议。从源码结构看整个 Agent 由四个 Python 文件 一个脚本组成应用入口、Agent 核心库、Supabase 版本实现、Postgres 版本实现以及负责构建与启动的 run_agent.sh。双数据库变体架构Supabase 与 PostgreSQL这是理解本项目最重要的一个设计决策。官方文档明确指出该 Agent 提供两个变体Supabase 版本gsam_supabase_agent.py通过 Supabase 官方 Python 客户端完成数据库读写适合直接使用 Supabase 托管服务PostgreSQL 版本gsam_postgres_agent.py通过 asyncpg 直连 PostgreSQL适合自建数据库或本地开发。两者在业务逻辑上完全一致——都负责拉取会话历史、存储用户消息、调用 Agent、回存应答——差异主要体现在数据库访问方式上Supabase 版本使用create_client(SUPABASE_URL, SUPABASE_SERVICE_KEY)创建客户端通过supabase.table(messages).select(...)链式调用完成查询应答消息以message_typeai落库并附带{request_id: request.request_id}元数据Postgres 版本在 FastAPI 的lifespan中通过asyncpg.create_pool(DATABASE_URL)创建连接池查询使用参数化 SQL$1、$2占位符避免注入风险应答消息以message_typeassistant落库。关键点在于数据库类型是自动判定的。在 gsam_ottomator_agent_app.py 中agent_db_type supabase if os.getenv(SUPABASE_URL) else postgres即只要.env中配置了SUPABASE_URL就走 Supabase 模式留空则自动切换为 Postgres 模式。两个 HTTP 端点会再次校验当前模式若模式不匹配则返回400 Invalid agent database type错误码GSAE-E010/GPAE-E010这一双保险设计可以避免误调导致的数据错乱。前置条件根据文档要求部署前需要准备Python 3.11 或更高版本基础镜像 base_python_docker/Dockerfile 基于python:3.11-slim构建与本要求一致pipPython 包管理器PostgreSQL 数据库或 Supabase 账号二选一对以下技术栈有基本了解FastAPI 与异步 PythonRESTful APIPydantic 模型环境变量PostgreSQLPostgres 版本所需核心组件解析1. FastAPI 应用认证、请求处理与图片服务gsam_ottomator_agent_app.py 是统一的应用入口聚合了两种数据库变体对外提供Bearer Token 认证通过环境变量API_BEARER_TOKEN校验请求头中的Authorization: Bearer token未配置该变量时返回 500token 不匹配时返回 401异步端点处理所有端点为async函数配合Depends(verify_token)做依赖注入式的安全校验结构化请求校验使用 Pydantic 的AgentRequest/AgentResponse模型进行请求体解析与响应约束错误处理与 HTTP 状态码统一以HTTPException抛出带错误码的异常信息CORS 中间件两个变体的init_fastapi_app()均配置了CORSMiddleware允许任意来源、方法与请求头方便 Live Agent Studio 前端跨域调用。应用对外暴露三个 HTTP 端点方法路径说明POST/api/gsam-supabase-agentSupabase 模式下的 Agent 入口POST/api/gsam-postgres-agentPostgres 模式下的 Agent 入口GET/api/image/{image_name}提供本地生成的图片文件读取./images/目录值得留意的是入口层还定义了一个CommonHeadersPydantic 模型包含host与scheme字段用于从请求头中提取主机名与协议。这在图片生成工具中至关重要Agent 生成的图片保存在本地./images/目录随后会被拼接成{scheme}://{host}/api/image/{image_name}形式的可访问 URL 返回给调用方。2. 数据模型请求与响应文档给出了两个核心 Pydantic 模型实际源码gsam_supabase_agent.py与文档完全一致class AgentRequest(BaseModel): query: str # 用户的输入文本 user_id: str # 用户的唯一标识 request_id: str # 本次请求的唯一标识 session_id: str # 当前会话 ID用于多轮对话 class AgentResponse(BaseModel): success: bool # 请求是否处理成功session_id是会话记忆的锚点Agent 会根据它从数据库拉取历史消息、存储新消息从而在多次请求之间维持连贯的上下文。3. 数据库 Schemamessages 表两个变体共用同一张messages表结构文档给出了 Supabase 侧的结构描述messages ( id: uuid primary key created_at: timestamp with time zone session_id: text message: jsonb { type: string # human 或 assistant content: string # 消息内容 data: jsonb # 可选附加数据 } )同时文档提供了可直接执行的建表 SQL包含索引与实时发布配置-- 启用 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); ALTER publication supabase_realtime ADD TABLE messages;注意若使用 Supabasepgcrypto扩展默认已启用可跳过第一条语句。session_id与created_at上的两个索引分别支撑会话历史查询与按时间排序ALTER publication supabase_realtime ADD TABLE messages则让消息表订阅 Supabase 实时通道便于前端即时刷新对话。Postgres 版本的查询逻辑可在 gsam_postgres_agent.py 中看到对应实现按session_id过滤、按created_at DESC倒序取最近 10 条再反转回时间正序。Agent 核心Pydantic AI 驱动的七类工具Agent 的智能体本体位于 gsam_agent_lib.py基于Pydantic AI框架构建这也是它与其它 oTTomator Agent 的最大差异点。模型与提示词配置模型初始化逻辑如下对应源码 gsam_agent_lib.pydefault_llm_provider cgsl.get_par_value(DEFAULT_LLM_PROVIDER, openai) if default_llm_provider openrouter: model_name cgsl.get_par_value(OPENROUTER_MODEL_NAME) model_params[api_key] cgsl.get_par_value(OPENROUTER_API_KEY) model_params[base_url] https://openrouter.ai/api/v1 else: model_name cgsl.get_par_value(OPENAI_MODEL_NAME, gpt-4o-mini) model_params[api_key] cgsl.get_par_value(OPENAI_API_KEY)默认 LLM 供应商为openai默认模型gpt-4o-mini可通过DEFAULT_LLM_PROVIDERopenrouter切换到 OpenRouter此时需配置OPENROUTER_API_KEY与OPENROUTER_MODEL_NAME系统提示词来自配置项AGENT_SYSTEM_PROMPT对应 config/agent_system_prompt.txt——该提示词把 Agent 塑造成 GenericSuite 库与软件开发的双料专家并严格限定其只响应七类任务Agent 实例设置retries2即单轮调用失败后自动重试通过logfire.configure(send_to_logfireif-token-present)接入 Logfire 可观测性存在 token 时才上报。七个功能工具Agent 通过pydantic_ai_agent.tool装饰器注册了七个工具每个工具都在 系统提示词 中予以声明工具函数能力底层实现generate_app_ideas生成应用创意IdeationLib.process_ideation_form按钮索引 0generate_app_name生成应用命名建议IdeationLib.process_ideation_form按钮索引 1generate_app_description生成应用描述与数据库表定义IdeationLib.process_ideation_form按钮索引 2generate_ppt_slides生成 PowerPoint 幻灯片内容IdeationLib.process_ideation_form按钮索引 3generate_json_and_code生成 GenericSuite 兼容 JSON LangChain 兼容 Python 代码CodeGenLib.process_json_and_code_generationgenerate_images基于文本生成图片cgsl.image_generation默认 HuggingFace Fluxgenerate_video基于文本生成视频cgsl.video_generation默认 Rhymes Allegro前四个创意类工具共用一个get_ideation_result(user_query, button_index)辅助函数源码它从get_ideation_from_prompt_config()与get_buttons_config_for_prompt()读取按钮配置根据按钮索引选择对应的生成脚本创意、命名、描述、PPT最终交给IdeationLib执行。四个创意工具的 Docstring 也说明了输出形式应用创意返回创意清单命名工具返回命名建议描述工具返回“描述 数据库 schema”PPT 工具返回生成好的演示文稿 URL。图片与视频工具内部带有 Mock 开关MOCK_IMAGES False、MOCK_VIDEOS True便于在未配置对应 API Key 时先行联调流程。图片工具会结合请求头动态构造可访问的图片 URL详见上一节CommonHeaders的说明视频工具则返回 S3 托管地址。RAG 增强文档检索三件套除七个业务工具外Agent 还注册了三个 RAG 工具源码使其能够基于向量检索回答 GenericSuite / Pydantic AI 文档相关问题retrieve_relevant_documentation先通过 OpenAItext-embedding-3-small模型将查询文本向量化再调用 Supabase RPCmatch_site_pages检索 top-5 相关文档分块并格式化返回list_documentation_pages从site_pages表查询所有metadata-source pydantic_ai_docs的唯一 URL 列表get_page_content按chunk_number顺序拼接指定 URL 的完整页面内容。这组工具说明 GSAM Agent 不只是“生成器”还具备“文档问答”能力适合把它当作 GenericSuite 生态的技术顾问来用。环境变量配置详解文档强调使用 Docker 时即使值包含特殊字符也不要用引号包裹环境变量值Docker 会正确处理。所有配置都在.env文件中设置或使用操作系统环境变量。数据库配置Supabase 模式必需变量SUPABASE_URLyour-project-url SUPABASE_SERVICE_KEYyour-service-key API_BEARER_TOKENyour-token-herePostgreSQL 模式必需变量DATABASE_URLpostgresql://user:passwordlocalhost:5432/dbname API_BEARER_TOKENyour-chosen-tokenDATABASE_URL的标准格式为postgresql://[user]:[password][host]:[port]/[database_name]LLM 配置OPENROUTER_API_KEYyour-api-key-here OPENROUTER_MODEL_NAMEyour-model-name-here结合 app_config.json 可以看到项目的 LLM 供应商体系远比文档列出的更丰富除 OpenRouter 外还内置了openai、together_ai、aimlapi、groq、nvidia、huggingface、xaiGrok等供应商及其可用模型清单例如 OpenRouter 下的google/gemini-2.0-flash-exp:free、deepseek/deepseek-r1:freeOpenAI 下的gpt-4o、gpt-4o-mini等。Agent 运行只需保证DEFAULT_LLM_PROVIDER指向的供应商及其对应 API Key 可用。图片生成配置# 使用 HuggingFace 与 Flux 生成图片 HUGGINGFACE_API_KEYyour-api-key-here配置文件中TEXT_TO_IMAGE_PROVIDERS将 huggingface模型black-forest-labs/FLUX.1-dev、FLUX.1-schnell与 openai模型dall-e-3、gpt-4o列为可用图片供应商。视频生成配置# 使用 Rhymes Allegro 生成视频 RHYMES_ALLEGRO_API_KEYyour-api-key-here配置文件中TEXT_TO_VIDEO_PROVIDERS将 rhymes 的allegro模型列为唯一视频供应商。安装与运行方式一Docker 安装推荐项目通过 Makefile 封装了全部 Docker 操作底层由 run_agent.sh 执行。1. 构建基础镜像并安装构建ottomator/base-python:latest基础镜像与gsam-python-agent应用镜像cd genericsuite-app-maker/gsam_ottomator_agent make install2. 运行容器cd genericsuite-app-maker/gsam_ottomator_agent make run启动后 Agent 服务位于http://localhost:8001。make run实际执行的是docker run -v $(pwd)/..:/app -d --name gsam-python-agent -p 8001:8001 --env-file .env gsam-python-agent——注意它通过--env-file .env注入环境变量并将宿主目录以卷挂载到容器/app因此本地修改代码无需重建镜像即可生效。3. 重启容器停止并重新运行cd genericsuite-app-maker/gsam_ottomator_agent make restart4. 停止并销毁容器cd genericsuite-app-maker/gsam_ottomator_agent make stop此外make logs可实时查看容器日志make requirements可在虚拟环境中安装并冻结依赖到requirements.txt。底层镜像关系为基础镜像 base_python_docker/Dockerfilepython:3.11-slim 依赖安装 非 root 用户appuser→ 应用镜像 Dockerfile基于ottomator/base-python:latest默认端口 8001启动时执行run_agent.sh run_uvicorn_server。若需切换数据库变体可在应用 Dockerfile 中按注释提示将 uvicorn 启动模块在gsam_supabase_agent:app与gsam_postgres_agent:app之间切换——不过在自动判定逻辑下直接通过.env控制即可。方式二本地安装Docker 替代方案1. 创建并激活虚拟环境安装依赖python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 pip install -r requirements.txt若本地尚无requirements.txt可先运行bash ./run_agent.sh requirements脚本会在虚拟环境中安装 fastapi、uvicorn、pydantic-ai、supabase、asyncpg、nest_asyncio、streamlit、python-pptx、openai、llama-index 等全套依赖并pip freeze生成锁定文件。2. 启动 AgentSupabase 版本——在.env中设置SUPABASE_URL与SUPABASE_SERVICE_KEY然后uvicorn gsam_ottomator_agent_app:app --host 0.0.0.0 --port 8001PostgreSQL 版本——设置DATABASE_URL并在.env中将SUPABASE_URL与SUPABASE_SERVICE_KEY留空然后执行与上面相同的 uvicorn 命令。两种本地启动都统一指向gsam_ottomator_agent_app:app这个聚合入口由入口自动完成数据库模式选择。发起首次请求服务启动后可用 curl 或任意 HTTP 客户端验证 Agent 是否工作正常。请求体中四个字段query、user_id、request_id、session_id缺一不可Authorization头必须与.env中的API_BEARER_TOKEN完全一致。Supabase 版本curl -X POST http://localhost:8001/api/gsam-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 }Postgres 版本curl -X POST http://localhost:8001/api/gsam-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}。处理流程为以 Supabase 版本为例见 gsam_supabase_agent.py按session_id拉取最近 10 条会话历史 → 存储用户的human消息 → 调用run_agent执行 Agent → 存储ai应答消息附带request_id→ 返回成功标志。若任一环节异常Agent 会向会话写入一条带错误详情的消息并以success: false返回DEBUG 模式下则直接抛出异常。故障排查文档列出的常见问题及对策如下认证错误Authentication Errors核对环境中的 Bearer Token检查Authorization请求头的格式必须为Bearer token确保 Token 与环境中配置的值完全一致包括前后空格。数据库连接问题Database Connection IssuesSupabase核对 Supabase 凭据验证messages表的权限设置PostgreSQL检查DATABASE_URL格式是否正确确认数据库用户权限、数据库实例运行状态与表是否已正确创建。性能问题Performance Problems排查数据库查询性能考虑对高频访问数据做缓存PostgreSQL监控连接池使用情况必要时调整池大小默认配置对多数场景已足够。结合源码还可补充两条排查线索一是入口层会校验数据库模式若返回400 Invalid agent database type说明.env中的SUPABASE_URL与你请求的端点不匹配二是图片请求返回 404 时需检查./images/目录与GET /api/image/{image_name}的文件服务逻辑。总结GSAM Python FastAPI Agent 展示了如何在 oTTomator Live Agent Studio 生态中构建一个“生成式研发助手”以 Pydantic AI 为智能体框架通过七个领域工具覆盖从创意、命名、描述、PPT 到 CRUD 代码与图文视频生成的全链路以 Supabase/PostgreSQL 双实现满足不同部署环境并用 Bearer Token、会话历史、RAG 文档问答等能力补齐了工程化闭环。对于想要在 Live Agent Studio 上快速搭建垂直领域 Agent 的开发者而言本项目的文件组织入口 / 库 / 双变体 / 构建脚本分层清晰本身就是一份很好的参考范式。若想深入了解其背后的配置与提示词设计可继续查阅 app_config.json供应商与模型矩阵、生成开关与 agent_system_prompt.txt任务边界与工具约束并结合 项目根 README 了解 GSAM 的整体定位。【免费下载链接】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），仅供参考 GenericSuite App Maker（GSAM）Python FastAPI Agent 实战指南：把 AI 应用开发助手接入 oTTomator Live Agent Studio
GenericSuite App MakerGSAMPython FastAPI Agent 实战指南把 AI 应用开发助手接入 oTTomator Live Agent Studio【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文是一份围绕 oTTomator Agents 仓库中 GSAM Python FastAPI Agent 的完整技术指南。它讲解如何基于 Pydantic AI 与 FastAPI 构建一个能生成应用创意、命名、PPT 内容、数据库表定义乃至可运行的 CRUD JSON 与 Python 代码的 AI 开发助手并把它无缝部署到 oTTomator Live Agent Studio 平台。读完本文你将掌握该 Agent 的双数据库变体架构、七类核心工具、环境变量配置、Docker/本地两种部署方式以及完整的请求调试流程。项目概览一个为软件研发流程服务的 AI AgentGSAMGenericSuite App MakerPython FastAPI Agent 是一个面向软件研发全流程的 AI 助手。它允许用户仅通过一段自然语言文本提示即可依次产出创新应用创意生成Innovative App Ideas Generation围绕独特功能、目标受众和潜在用途构思 Web/移动端应用概念应用命名Names Generation为软件应用提出朗朗上口、富有创意的名字建议PowerPoint 内容创作PowerPoint Content Creation起草演示文稿幻灯片内容并为生成配图提供提示词建议应用描述与数据表定义App Description and Table Definitions撰写完整的应用描述与详细的数据库表结构定义CRUD JSON 与 Python 代码生成CRUD JSON and Python Code Generation产出与 GenericSuite 兼容的通用 CRUD 编辑器配置 JSON以及配套的 Python 工具代码。除此之外该 Agent 还具备处理自然语言查询、维护多轮会话历史、对接外部 AI 模型、存取会话数据、处理认证与安全等平台级能力并兼容 oTTomator Live Agent Studio 的接入协议。从源码结构看整个 Agent 由四个 Python 文件 一个脚本组成应用入口、Agent 核心库、Supabase 版本实现、Postgres 版本实现以及负责构建与启动的 run_agent.sh。双数据库变体架构Supabase 与 PostgreSQL这是理解本项目最重要的一个设计决策。官方文档明确指出该 Agent 提供两个变体Supabase 版本gsam_supabase_agent.py通过 Supabase 官方 Python 客户端完成数据库读写适合直接使用 Supabase 托管服务PostgreSQL 版本gsam_postgres_agent.py通过 asyncpg 直连 PostgreSQL适合自建数据库或本地开发。两者在业务逻辑上完全一致——都负责拉取会话历史、存储用户消息、调用 Agent、回存应答——差异主要体现在数据库访问方式上Supabase 版本使用create_client(SUPABASE_URL, SUPABASE_SERVICE_KEY)创建客户端通过supabase.table(messages).select(...)链式调用完成查询应答消息以message_typeai落库并附带{request_id: request.request_id}元数据Postgres 版本在 FastAPI 的lifespan中通过asyncpg.create_pool(DATABASE_URL)创建连接池查询使用参数化 SQL$1、$2占位符避免注入风险应答消息以message_typeassistant落库。关键点在于数据库类型是自动判定的。在 gsam_ottomator_agent_app.py 中agent_db_type supabase if os.getenv(SUPABASE_URL) else postgres即只要.env中配置了SUPABASE_URL就走 Supabase 模式留空则自动切换为 Postgres 模式。两个 HTTP 端点会再次校验当前模式若模式不匹配则返回400 Invalid agent database type错误码GSAE-E010/GPAE-E010这一双保险设计可以避免误调导致的数据错乱。前置条件根据文档要求部署前需要准备Python 3.11 或更高版本基础镜像 base_python_docker/Dockerfile 基于python:3.11-slim构建与本要求一致pipPython 包管理器PostgreSQL 数据库或 Supabase 账号二选一对以下技术栈有基本了解FastAPI 与异步 PythonRESTful APIPydantic 模型环境变量PostgreSQLPostgres 版本所需核心组件解析1. FastAPI 应用认证、请求处理与图片服务gsam_ottomator_agent_app.py 是统一的应用入口聚合了两种数据库变体对外提供Bearer Token 认证通过环境变量API_BEARER_TOKEN校验请求头中的Authorization: Bearer token未配置该变量时返回 500token 不匹配时返回 401异步端点处理所有端点为async函数配合Depends(verify_token)做依赖注入式的安全校验结构化请求校验使用 Pydantic 的AgentRequest/AgentResponse模型进行请求体解析与响应约束错误处理与 HTTP 状态码统一以HTTPException抛出带错误码的异常信息CORS 中间件两个变体的init_fastapi_app()均配置了CORSMiddleware允许任意来源、方法与请求头方便 Live Agent Studio 前端跨域调用。应用对外暴露三个 HTTP 端点方法路径说明POST/api/gsam-supabase-agentSupabase 模式下的 Agent 入口POST/api/gsam-postgres-agentPostgres 模式下的 Agent 入口GET/api/image/{image_name}提供本地生成的图片文件读取./images/目录值得留意的是入口层还定义了一个CommonHeadersPydantic 模型包含host与scheme字段用于从请求头中提取主机名与协议。这在图片生成工具中至关重要Agent 生成的图片保存在本地./images/目录随后会被拼接成{scheme}://{host}/api/image/{image_name}形式的可访问 URL 返回给调用方。2. 数据模型请求与响应文档给出了两个核心 Pydantic 模型实际源码gsam_supabase_agent.py与文档完全一致class AgentRequest(BaseModel): query: str # 用户的输入文本 user_id: str # 用户的唯一标识 request_id: str # 本次请求的唯一标识 session_id: str # 当前会话 ID用于多轮对话 class AgentResponse(BaseModel): success: bool # 请求是否处理成功session_id是会话记忆的锚点Agent 会根据它从数据库拉取历史消息、存储新消息从而在多次请求之间维持连贯的上下文。3. 数据库 Schemamessages 表两个变体共用同一张messages表结构文档给出了 Supabase 侧的结构描述messages ( id: uuid primary key created_at: timestamp with time zone session_id: text message: jsonb { type: string # human 或 assistant content: string # 消息内容 data: jsonb # 可选附加数据 } )同时文档提供了可直接执行的建表 SQL包含索引与实时发布配置-- 启用 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); ALTER publication supabase_realtime ADD TABLE messages;注意若使用 Supabasepgcrypto扩展默认已启用可跳过第一条语句。session_id与created_at上的两个索引分别支撑会话历史查询与按时间排序ALTER publication supabase_realtime ADD TABLE messages则让消息表订阅 Supabase 实时通道便于前端即时刷新对话。Postgres 版本的查询逻辑可在 gsam_postgres_agent.py 中看到对应实现按session_id过滤、按created_at DESC倒序取最近 10 条再反转回时间正序。Agent 核心Pydantic AI 驱动的七类工具Agent 的智能体本体位于 gsam_agent_lib.py基于Pydantic AI框架构建这也是它与其它 oTTomator Agent 的最大差异点。模型与提示词配置模型初始化逻辑如下对应源码 gsam_agent_lib.pydefault_llm_provider cgsl.get_par_value(DEFAULT_LLM_PROVIDER, openai) if default_llm_provider openrouter: model_name cgsl.get_par_value(OPENROUTER_MODEL_NAME) model_params[api_key] cgsl.get_par_value(OPENROUTER_API_KEY) model_params[base_url] https://openrouter.ai/api/v1 else: model_name cgsl.get_par_value(OPENAI_MODEL_NAME, gpt-4o-mini) model_params[api_key] cgsl.get_par_value(OPENAI_API_KEY)默认 LLM 供应商为openai默认模型gpt-4o-mini可通过DEFAULT_LLM_PROVIDERopenrouter切换到 OpenRouter此时需配置OPENROUTER_API_KEY与OPENROUTER_MODEL_NAME系统提示词来自配置项AGENT_SYSTEM_PROMPT对应 config/agent_system_prompt.txt——该提示词把 Agent 塑造成 GenericSuite 库与软件开发的双料专家并严格限定其只响应七类任务Agent 实例设置retries2即单轮调用失败后自动重试通过logfire.configure(send_to_logfireif-token-present)接入 Logfire 可观测性存在 token 时才上报。七个功能工具Agent 通过pydantic_ai_agent.tool装饰器注册了七个工具每个工具都在 系统提示词 中予以声明工具函数能力底层实现generate_app_ideas生成应用创意IdeationLib.process_ideation_form按钮索引 0generate_app_name生成应用命名建议IdeationLib.process_ideation_form按钮索引 1generate_app_description生成应用描述与数据库表定义IdeationLib.process_ideation_form按钮索引 2generate_ppt_slides生成 PowerPoint 幻灯片内容IdeationLib.process_ideation_form按钮索引 3generate_json_and_code生成 GenericSuite 兼容 JSON LangChain 兼容 Python 代码CodeGenLib.process_json_and_code_generationgenerate_images基于文本生成图片cgsl.image_generation默认 HuggingFace Fluxgenerate_video基于文本生成视频cgsl.video_generation默认 Rhymes Allegro前四个创意类工具共用一个get_ideation_result(user_query, button_index)辅助函数源码它从get_ideation_from_prompt_config()与get_buttons_config_for_prompt()读取按钮配置根据按钮索引选择对应的生成脚本创意、命名、描述、PPT最终交给IdeationLib执行。四个创意工具的 Docstring 也说明了输出形式应用创意返回创意清单命名工具返回命名建议描述工具返回“描述 数据库 schema”PPT 工具返回生成好的演示文稿 URL。图片与视频工具内部带有 Mock 开关MOCK_IMAGES False、MOCK_VIDEOS True便于在未配置对应 API Key 时先行联调流程。图片工具会结合请求头动态构造可访问的图片 URL详见上一节CommonHeaders的说明视频工具则返回 S3 托管地址。RAG 增强文档检索三件套除七个业务工具外Agent 还注册了三个 RAG 工具源码使其能够基于向量检索回答 GenericSuite / Pydantic AI 文档相关问题retrieve_relevant_documentation先通过 OpenAItext-embedding-3-small模型将查询文本向量化再调用 Supabase RPCmatch_site_pages检索 top-5 相关文档分块并格式化返回list_documentation_pages从site_pages表查询所有metadata-source pydantic_ai_docs的唯一 URL 列表get_page_content按chunk_number顺序拼接指定 URL 的完整页面内容。这组工具说明 GSAM Agent 不只是“生成器”还具备“文档问答”能力适合把它当作 GenericSuite 生态的技术顾问来用。环境变量配置详解文档强调使用 Docker 时即使值包含特殊字符也不要用引号包裹环境变量值Docker 会正确处理。所有配置都在.env文件中设置或使用操作系统环境变量。数据库配置Supabase 模式必需变量SUPABASE_URLyour-project-url SUPABASE_SERVICE_KEYyour-service-key API_BEARER_TOKENyour-token-herePostgreSQL 模式必需变量DATABASE_URLpostgresql://user:passwordlocalhost:5432/dbname API_BEARER_TOKENyour-chosen-tokenDATABASE_URL的标准格式为postgresql://[user]:[password][host]:[port]/[database_name]LLM 配置OPENROUTER_API_KEYyour-api-key-here OPENROUTER_MODEL_NAMEyour-model-name-here结合 app_config.json 可以看到项目的 LLM 供应商体系远比文档列出的更丰富除 OpenRouter 外还内置了openai、together_ai、aimlapi、groq、nvidia、huggingface、xaiGrok等供应商及其可用模型清单例如 OpenRouter 下的google/gemini-2.0-flash-exp:free、deepseek/deepseek-r1:freeOpenAI 下的gpt-4o、gpt-4o-mini等。Agent 运行只需保证DEFAULT_LLM_PROVIDER指向的供应商及其对应 API Key 可用。图片生成配置# 使用 HuggingFace 与 Flux 生成图片 HUGGINGFACE_API_KEYyour-api-key-here配置文件中TEXT_TO_IMAGE_PROVIDERS将 huggingface模型black-forest-labs/FLUX.1-dev、FLUX.1-schnell与 openai模型dall-e-3、gpt-4o列为可用图片供应商。视频生成配置# 使用 Rhymes Allegro 生成视频 RHYMES_ALLEGRO_API_KEYyour-api-key-here配置文件中TEXT_TO_VIDEO_PROVIDERS将 rhymes 的allegro模型列为唯一视频供应商。安装与运行方式一Docker 安装推荐项目通过 Makefile 封装了全部 Docker 操作底层由 run_agent.sh 执行。1. 构建基础镜像并安装构建ottomator/base-python:latest基础镜像与gsam-python-agent应用镜像cd genericsuite-app-maker/gsam_ottomator_agent make install2. 运行容器cd genericsuite-app-maker/gsam_ottomator_agent make run启动后 Agent 服务位于http://localhost:8001。make run实际执行的是docker run -v $(pwd)/..:/app -d --name gsam-python-agent -p 8001:8001 --env-file .env gsam-python-agent——注意它通过--env-file .env注入环境变量并将宿主目录以卷挂载到容器/app因此本地修改代码无需重建镜像即可生效。3. 重启容器停止并重新运行cd genericsuite-app-maker/gsam_ottomator_agent make restart4. 停止并销毁容器cd genericsuite-app-maker/gsam_ottomator_agent make stop此外make logs可实时查看容器日志make requirements可在虚拟环境中安装并冻结依赖到requirements.txt。底层镜像关系为基础镜像 base_python_docker/Dockerfilepython:3.11-slim 依赖安装 非 root 用户appuser→ 应用镜像 Dockerfile基于ottomator/base-python:latest默认端口 8001启动时执行run_agent.sh run_uvicorn_server。若需切换数据库变体可在应用 Dockerfile 中按注释提示将 uvicorn 启动模块在gsam_supabase_agent:app与gsam_postgres_agent:app之间切换——不过在自动判定逻辑下直接通过.env控制即可。方式二本地安装Docker 替代方案1. 创建并激活虚拟环境安装依赖python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 pip install -r requirements.txt若本地尚无requirements.txt可先运行bash ./run_agent.sh requirements脚本会在虚拟环境中安装 fastapi、uvicorn、pydantic-ai、supabase、asyncpg、nest_asyncio、streamlit、python-pptx、openai、llama-index 等全套依赖并pip freeze生成锁定文件。2. 启动 AgentSupabase 版本——在.env中设置SUPABASE_URL与SUPABASE_SERVICE_KEY然后uvicorn gsam_ottomator_agent_app:app --host 0.0.0.0 --port 8001PostgreSQL 版本——设置DATABASE_URL并在.env中将SUPABASE_URL与SUPABASE_SERVICE_KEY留空然后执行与上面相同的 uvicorn 命令。两种本地启动都统一指向gsam_ottomator_agent_app:app这个聚合入口由入口自动完成数据库模式选择。发起首次请求服务启动后可用 curl 或任意 HTTP 客户端验证 Agent 是否工作正常。请求体中四个字段query、user_id、request_id、session_id缺一不可Authorization头必须与.env中的API_BEARER_TOKEN完全一致。Supabase 版本curl -X POST http://localhost:8001/api/gsam-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 }Postgres 版本curl -X POST http://localhost:8001/api/gsam-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}。处理流程为以 Supabase 版本为例见 gsam_supabase_agent.py按session_id拉取最近 10 条会话历史 → 存储用户的human消息 → 调用run_agent执行 Agent → 存储ai应答消息附带request_id→ 返回成功标志。若任一环节异常Agent 会向会话写入一条带错误详情的消息并以success: false返回DEBUG 模式下则直接抛出异常。故障排查文档列出的常见问题及对策如下认证错误Authentication Errors核对环境中的 Bearer Token检查Authorization请求头的格式必须为Bearer token确保 Token 与环境中配置的值完全一致包括前后空格。数据库连接问题Database Connection IssuesSupabase核对 Supabase 凭据验证messages表的权限设置PostgreSQL检查DATABASE_URL格式是否正确确认数据库用户权限、数据库实例运行状态与表是否已正确创建。性能问题Performance Problems排查数据库查询性能考虑对高频访问数据做缓存PostgreSQL监控连接池使用情况必要时调整池大小默认配置对多数场景已足够。结合源码还可补充两条排查线索一是入口层会校验数据库模式若返回400 Invalid agent database type说明.env中的SUPABASE_URL与你请求的端点不匹配二是图片请求返回 404 时需检查./images/目录与GET /api/image/{image_name}的文件服务逻辑。总结GSAM Python FastAPI Agent 展示了如何在 oTTomator Live Agent Studio 生态中构建一个“生成式研发助手”以 Pydantic AI 为智能体框架通过七个领域工具覆盖从创意、命名、描述、PPT 到 CRUD 代码与图文视频生成的全链路以 Supabase/PostgreSQL 双实现满足不同部署环境并用 Bearer Token、会话历史、RAG 文档问答等能力补齐了工程化闭环。对于想要在 Live Agent Studio 上快速搭建垂直领域 Agent 的开发者而言本项目的文件组织入口 / 库 / 双变体 / 构建脚本分层清晰本身就是一份很好的参考范式。若想深入了解其背后的配置与提示词设计可继续查阅 app_config.json供应商与模型矩阵、生成开关与 agent_system_prompt.txt任务边界与工具约束并结合 项目根 README 了解 GSAM 的整体定位。【免费下载链接】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），仅供参考