AG-UI RAG Agent 部署实战基于 Pydantic AI 与 CopilotKit 的共享状态 RAG 前后端集成指南【免费下载链接】ottomator-agentsAll the open source AI Agents hosted on the oTTomator Live Agent Studio platform!项目地址: https://gitcode.com/GitHub_Trending/ot/ottomator-agents本文围绕 AG-UI 版 RAG Agent 部署文档 展开系统讲解如何用 Pydantic AIAG-UI 协议 Next.js/CopilotKit 搭建一个带实时共享状态的检索增强生成RAG助手涵盖后端 ASGI 服务的安装、环境变量与数据库配置、文档摄取流水线、Agent 工具与 AG-UI 事件机制以及前端交互动作的接线方式。读完并照做后你可以在本地跑通「对话提问 → 向量/混合检索 → 检索结果实时同步到 UI」的完整链路。架构总览该项目的架构由四个部分组成引自部署文档的 Architecture Overview后端基于 Pydantic AI、启用 AG-UI 支持的 Agent以 ASGI 服务形式运行前端Next.js CopilotKit 组成的用户界面协议AG-UI用于 Agent 与用户界面之间的实时交互和共享状态shared state同步数据库PostgreSQL pgvector用于向量相似度检索。后端的核心入口是 agent.py。文件末尾agent.py#L368-L373通过rag_agent.to_ag_ui(depsStateDeps(RAGState()))把 Pydantic AI Agent 转换为 AG-UI 应用再用 uvicorn 监听0.0.0.0:8000——这正是文档中“服务启动在 http://localhost:8000”的由来。环境准备Prerequisites部署文档列出的前置条件如下已安装 pgvector 扩展的 PostgreSQLNode.js 18 及 npm/yarnPython 3.9OpenAI API Key或任何 OpenAI 兼容的 LLM 提供商。其中最后一条“兼容提供商”的能力由 providers.py 支撑get_llm_model()统一使用OpenAIProvider(base_url..., api_key...)构造 providers.py#L27-L29因此只需在环境变量中替换LLM_BASE_URL与LLM_API_KEY即可接入任意 OpenAI 兼容端点。后端部署1. 安装 Python 依赖cd agent pip install -r requirements.txtrequirements.txt 中与 AG-UI 直接相关的核心依赖是pydantic-ai[agui]0.1.0与ag-ui0.1.0数据库侧为asyncpg、psycopg2-binary、pgvectorWeb 框架为fastapi与uvicorn[standard]。部署文档的 Troubleshooting 一节也特别提示出现 AGUI 相关错误时应确认pydantic-ai[agui]已正确安装。2. 配置环境变量在agent目录下创建.env文件。部署文档给出的完整模板如下# LLM Configuration LLM_PROVIDERopenai LLM_MODELgpt-4 LLM_API_KEYyour-openai-api-key LLM_BASE_URLhttps://api.openai.com/v1 # Optional for OpenAI # Database Configuration DATABASE_URLpostgresql://user:passwordlocalhost:5432/ragdb DB_POOL_MIN_SIZE5 DB_POOL_MAX_SIZE20 # Embeddings EMBEDDING_MODELtext-embedding-3-small EMBEDDING_DIMENSIONS1536 # Optional: LLM Settings LLM_TEMPERATURE0.7 LLM_MAX_TOKENS4096这些变量由 settings.py 中的Settings基于pydantic_settings.BaseSettings大小写不敏感、extraignore解析。结合源码逐字段说明如下环境变量对应字段默认值说明DATABASE_URLdatabase_url必填settings.py#L23-L26PostgreSQL 连接串需已启用 pgvectorLLM_PROVIDERllm_provideropenaiLLM 提供商标识openai/anthropic/gemini/ollama 等LLM_API_KEYllm_api_key必填LLM 提供商 API KeyLLM_MODELllm_modelgpt-4o-mini对话/检索模型名文档示例写gpt-4以你实际填写为准LLM_BASE_URLllm_base_urlhttps://api.openai.com/v1OpenAI 兼容端点的 Base URLDB_POOL_MIN_SIZEdb_pool_min_size10asyncpg 连接池最小连接数AgentDependencies建池时使用见 dependencies.py#L31-L35DB_POOL_MAX_SIZEdb_pool_max_size20连接池最大连接数EMBEDDING_MODELembedding_modeltext-embedding-3-small嵌入模型EMBEDDING_DIMENSIONSembedding_dimension1536嵌入向量维度另外三个搜索行为参数在Settings中有默认值settings.py#L50-L63可用于检索调优DEFAULT_MATCH_COUNT默认返回条数默认 10MAX_MATCH_COUNT允许的最大返回条数默认 50tools.py#L46 会对请求条数做min(match_count, max_match_count)截断DEFAULT_TEXT_WEIGHT混合检索中文本匹配权重默认 0.3取值会被钳制到 0–1 区间见 tools.py#L111。两点源码级提示其一模板中的LLM_TEMPERATURE与LLM_MAX_TOKENS目前并未被Settings声明为字段而配置类设置了extraignore从源码结构看这两个变量当前不会生效其二LLM_API_KEY缺失时load_settings()会抛出带明确提示的ValueErrorsettings.py#L88-L98便于快速定位问题。3. 初始化数据库python -m agent.utils.db_utils init数据库结构定义在 schema.sql包含建表所需的完整 DDL 与检索函数启用vector、uuid-ossp、pg_trgm三个扩展documents表UUID 主键、title、source、content、metadata JSONB带 GIN 索引、created_at/updated_atchunks表embedding vector(1536)、chunk_index、token_count等字段并建立 ivfflat 向量索引vector_cosine_ops与 trigram GIN 索引两个核心检索函数后面“检索机制”一节展开match_chunks()schema.sql#L41-L72与hybrid_search()schema.sql#L74-L136。注意chunks.embedding的维度被硬编码为vector(1536)与text-embedding-3-small的输出维度一致若更换为不同维度输出的嵌入模型可以推断需要同步修改 schema 中的向量列定义否则入库会失败。4. 摄取文档python -m agent.ingestion.ingest --documents ./documents --clean摄取入口为 ingest.py 中的DocumentIngestionPipeline--documents指定 Markdown 文档目录仓库自带 agent/documents 共 21 篇示例文档可直接使用--clean表示摄取前清空既有数据。流水线内部由 chunker.py 与 embedder.py 支撑ChunkingConfig支持chunk_size、chunk_overlap、max_chunk_size以及use_semantic_chunking等参数ingest.py#L61-L68。5. 启动 AGUI 服务python agent/agent.py服务启动后监听 http://localhost:8000前端通过 AG-UI 协议与其通信。前端部署npm install # 或 yarn installnpm run dev # 或 yarn dev前端运行在 http://localhost:3000。使用流程引自文档 Usage 一节浏览器打开 http://localhost:3000RAG Assistant 出现在右侧边栏提问即可触发对知识库的检索检索到的 chunks 显示在左侧面板点击 chunk 可展开查看完整内容与元数据使用过滤框可在已检索 chunks 内二次过滤。共享状态Shared StateAG-UI 架构的核心是前后端共享同一份类型化状态。文档定义的RAGStateTypeScript 类型如下type RAGState { retrieved_chunks: RetrievedChunk[]; // Chunks from knowledge base current_query: SearchQuery | null; // Current search query search_history: SearchQuery[]; // History of searches selected_chunk_id: string | null; // Currently highlighted chunk total_chunks_in_kb: number; // Total chunks in database knowledge_base_status: string; // Status of the knowledge base }后端由 agent.py#L39-L64 中同构的 Pydantic 模型RAGState实现并用deps_typeStateDeps[RAGState]注入 Agentagent.py#L68-L72retrieved_chunks检索到的 chunks 列表元素为RetrievedChunk含chunk_id、document_id、content、similarity、metadata、document_title、document_source、highlight等字段定义于 agent.py#L19-L28current_query/search_history当前查询与历史查询SearchQuery记录query、timestamp、match_count默认 10、search_typesearch_knowledge_base工具在每次搜索后会把历史裁剪到最近 10 条agent.py#L110-L112selected_chunk_id当前高亮 chunktotal_chunks_in_kb/knowledge_base_status知识库规模与状态ready、indexing、error会实时反映在动态指令中。由于前端和后端对同一状态分别持有 TypeScript 类型与 Pydantic 模型Pydantic 的校验保证了状态写入时经过类型检查——这是文档所列架构收益Type Safety的具体落点。Agent 工具与 AG-UI 事件部署文档列出 5 个 Agent 工具与 agent.py 源码一一对应工具行为源码位置search_knowledge_base执行语义/混合检索并把结果写入共享状态agent.py#L75-L194clear_search_results清空检索结果、当前查询与选中项agent.py#L197-L215select_chunk在 UI 中高亮指定 chunkagent.py#L218-L235get_knowledge_base_stats查询chunks表计数并更新知识库状态agent.py#L238-L267display_search_results通过 AG-UI 自定义事件触发 UI 展示检索结果agent.py#L270-L292值得关注的实现细节有两点状态同步用StateSnapshotEvent每个工具执行完毕后都返回StateSnapshotEvent(typeEventType.STATE_SNAPSHOT, snapshotctx.deps.state.model_dump())把整份共享状态以快照事件推给前端保证 UI 与后端状态严格一致出错时也会清空retrieved_chunks并把knowledge_base_status写为error: ...后照样下发快照agent.py#L185-L194前端因此能感知检索失败。UI 触发用CustomEventdisplay_search_results返回CustomEvent(nameDisplaySearchResults, value{chunks, query, total_results})agent.py#L284-L292这是文档中“Custom Events”特性的具体实现路径。反向链路前端 → Agent由 CopilotKit 的useCopilotAction暴露前端动作。文档列出两个动作均在 page.tsx 中注册highlightChunk高亮并展开某个 chunk与setThemeColor改变 UI 主题色注册代码见 page.tsx#L54-L82。页面同时通过useCoAgent接入 AG-UI Agent 并消费共享状态。此外agent.py#L295-L365 的rag_agent.instructions实现了动态系统指令每轮运行时把知识库状态、chunk 总数、已检索内容摘要Top 5 各截断 200 字符注入提示词而静态系统提示词MAIN_SYSTEM_PROMPTprompts.py约定了“仅在用户明确需要知识库信息时才检索、问候类消息直接对话、优先混合检索”等搜索策略。检索机制语义检索与混合检索search_knowledge_base根据search_type参数semantic或hybrid分派到 tools.py 中的两个底层函数语义检索semantic_searchtools.py#L22-L79先经AgentDependencies.get_embedding()调用嵌入 API 生成查询向量再转换为 PostgreSQL vector 字面量字符串最终执行数据库函数SELECT * FROM match_chunks($1::vector, $2)。SQL 侧的match_chunks用余弦距离排序并以1 - (c.embedding query_embedding)作为相似度得分schema.sql#L62。混合检索hybrid_searchtools.py#L82-L149执行hybrid_search($1::vector, $2, $3, $4)SQL 函数内部以vector_results余弦相似度与text_resultsts_rank_cd全文相关度做FULL OUTER JOIN融合得分公式为combined_score vector_sim * (1 - text_weight) text_sim * text_weightschema.sql#L125。text_weight默认 0.3Python 侧会将其钳制到[0, 1]混合结果中的vector_similarity与text_similarity会额外写入 chunk 的metadataagent.py#L142-L146供前端展示各得分来源。两个函数共同的健壮性设计异常时返回空列表而非抛出tools.py#L77-L79保证 Agent 对话流程不会因数据库瞬时故障中断连接与客户端由AgentDependencies统一管理initialize()建立 asyncpg 连接池与openai.AsyncOpenAI客户端cleanup()负责关闭连接池dependencies.py#L24-L48。定制化部署文档的 Customization 一节给出了三个扩展方向结合源码说明如下修改 Agent编辑 agent/agent.py用rag_agent.tool装饰器添加新工具修改RAGState模型以承载不同的共享状态调整搜索行为或打分逻辑可联动修改tools.py与schema.sql中的融合权重。修改前端编辑src/app/page.tsx调整 UI 布局与组件、为 chunks 增加新的可视化、定制 chunk 展示格式、新增前端动作仿照useCopilotAction的既有写法。修改摄取流水线agent/ingestion/支持更多文档格式、抽取自定义元数据、调整分块策略ChunkingConfig的chunk_size/chunk_overlap/use_semantic_chunking等、增加文档预处理步骤。故障排查常见问题文档 Troubleshooting 一节数据库连接错误确认 PostgreSQL 正在运行且DATABASE_URL凭据正确load_settings()会在缺少DATABASE_URL时给出针对性提示Agent 无响应确认 Agent 服务已运行在 8000 端口没有 chunks 显示确认已执行摄取脚本将文档写入数据库AGUI 报错确认pydantic-ai[agui]已正确安装。调试模式# 后端 PYTHONUNBUFFERED1 python agent/agent.py # 前端 npm run dev -- --verbosePYTHONUNBUFFERED1用于让日志实时刷出便于对照 AG-UI 事件流定位状态同步问题。相关实现与测试散落在 agent/utils/db_utils.py连接池管理min_size5、max_size20、command_timeout60与 agent/tests 目录中可作为进一步排查时的参照。架构收益小结文档总结的五个架构收益在此项目中都有明确落点实时同步由StateSnapshotEvent/CustomEvent驱动类型安全来自前后端各自维护的同构状态定义与 Pydantic 校验可扩展性来自 ASGI/uvicorn 服务形态灵活性来自 OpenAI 兼容的 provider 抽象与工具化的检索层用户体验则体现为 chunk 展开、高亮、过滤等交互能力。后续可演进方向包括认证与会话、chunk 反馈评分、UI 文档上传、增量索引与检索结果导出等文档 Next Steps 一节。【免费下载链接】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），仅供参考
