Python Local AI Agent基于 FastAPI Pydantic AI 的本地联网智能体实战指南【免费下载链接】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 仓库中的python-local-ai-agent目录系统讲解如何用 Python 构建一个完全本地化的 AI Agent 服务它基于 FastAPI 提供 OpenAI 兼容的 HTTP 端点通过 Pydantic AI 编排对话、借助 SearXNG 实现联网搜索、使用 Supabase 持久化多轮会话并兼容 Open WebUI 与 Ollama 等任意 OpenAI 兼容 LLM 提供方。读完本文你将掌握从环境配置、数据库建表、本地/容器化启动到通过 curl 与 OpenAI Python SDK 调用该服务的完整实战链路并理解其与仓库内 n8n 版本n8n_local_ai_agent.json在功能上的对等关系。一、项目定位Python 版本地 AI Agent 与 n8n 版的等价替代python-local-ai-agent是一个FastAPI 驱动的 AI Agent 服务它同时具备网络搜索、对话历史持久化与 OpenAI 兼容端点三大能力可对接 Ollama、OpenAI、OpenRouter 等任意 OpenAI 兼容的 LLM 提供方。官方 README 明确指出这份 Python 实现与同目录下的 n8n Agent 工作流n8n_local_ai_agent.json提供完全相同的功能两者在以下三个维度保持一致使用同一个数据库表n8n_chat_histories存储对话记录提供相同的 API 端点结构以兼容 Open WebUI都通过 SearXNG 实现联网搜索都能同时处理普通聊天消息与元数据metadata请求。从源码层面看Python 版的核心实现集中在 main.pymain.py内通过Agent承载主对话能力用metadata_agent处理 Open WebUI 发送的元数据请求并挂载web_search工具调用 SearXNG。两种方案的取舍非常简单偏好独立服务与更强的程序化控制选 Python 版偏好可视化工作流编排选 n8n 版。从n8n_local_ai_agent.json的节点结构可以看到n8n 版工作流同样包含「Postgres Chat Memory」「SearXNG」「Web Search Tool」「Ollama Chat Model」「Open WebUI Metadata LLM」等对等组件印证了两者架构一一对应。二、功能特性与运行前提2.1 核心特性一览README 列出的功能点如下其中大部分可以在 main.py 中找到直接对应的实现特性实现依据Pydantic AI Agent 与对话历史agent Agent(...)与message_historymessages传入机制基于 SearXNG 的联网搜索agent.tool装饰的web_search异步工具基于 Supabase 的对话持久化fetch_conversation_history/store_message两个数据库操作函数Bearer Token 认证verify_token依赖与HTTPBearer安全机制Docker 与 local-ai 网络集成docker-compose.yml 与 DockerfileOpenAI 兼容Ollama / OpenAI 等OpenAIModelOpenAIProvider(base_url..., api_key...)2.2 运行前提部署前需要准备以下四项基础设施Python 3.11Docker 镜像也基于python:3.11-slim构建见 DockerfileSupabase 项目用于对话历史持久化需要拿到项目 URL 与服务密钥SearXNG 实例用于联网搜索的元搜索引擎本地部署通常在localhost:8081容器网络内为http://searxng:8080Ollama 或 OpenAI API 访问作为底层 LLM其中 Ollama 需本地运行并预先拉取支持工具调用的模型。重要提醒.env.example 中明确强调若使用 Ollama务必选择支持 tools函数调用的模型否则 Agent 的联网搜索工具将无法正确触发。三、安装与环境配置3.1 克隆仓库并创建虚拟环境git clone https://github.com/coleam00/ottomator-agents.git cd ottomator-agents/python-local-ai-agent说明仓库为只读资源若你已在本地拥有该仓库可直接进入python-local-ai-agent目录执行后续步骤。# 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Linux/Mac: source venv/bin/activate # Windows: venv\Scripts\activate # 安装依赖 pip install -r requirements.txt依赖文件 requirements.txt 锁定了完整版本清单核心组件包括fastapi0.115.12、pydantic-ai0.2.16、supabase2.15.2、httpx0.28.1、openai1.84.0、uvicorn0.34.3、python-dotenv1.1.0等。其中pydantic-ai是 Agent 编排框架supabase负责数据库读写httpx驱动 SearXNG 搜索请求。3.2 配置环境变量复制示例环境文件并填入真实值cp .env.example .env.env.example 定义了全部配置项下表结合源码与官方注释给出完整说明变量作用示例值 / 默认行为LLM_BASE_URLOpenAI 兼容端点地址Ollamahttp://localhost:11434/v1OpenAIhttps://api.openai.com/v1OpenRouterhttps://openrouter.ai/api/v1。源码默认值为http://localhost:11434/v1见 main.py 的get_model()LLM_API_KEYAPI 密钥Ollama 通常填ollama即可源码默认值即为ollamaOpenRouter 需在官方平台注册获取LLM_CHOICE模型名称Ollama 示例qwen3:14bOpenAI 示例gpt-4o-miniOpenRouter 示例anthropic/claude-3.7-sonnet。源码默认qwen3:14bSUPABASE_URLSupabase 项目地址宿主机外运行http://localhost:8000local-ai 网络容器内http://kong:8000SUPABASE_SERVICE_KEYSupabase 服务密钥从你的 Supabase 项目获取注意使用 service key 而非 anon keySEARXNG_BASE_URLSearXNG 端点宿主机http://localhost:8081容器http://searxng:8080。源码默认http://localhost:8080BEARER_TOKENAPI 认证令牌自定义字符串即请求头Authorization: Bearer token中token的内容OPENAI_API_KEY仅供 demo 脚本使用配置后 openai_compatible_demo.py 会将其作为候选提供方列出3.3 数据库初始化Supabase 需要一张n8n_chat_histories表来存储会话消息。重要如果你已经为 n8n 版n8n_local_ai_agent.json建过该表则无需重复执行因为两个版本共享同一张表。建表 SQL 如下在 Supabase SQL Editor 中执行CREATE EXTENSION IF NOT EXISTS pgcrypto; CREATE TABLE n8n_chat_histories ( 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 n8n_chat_histories(session_id); CREATE INDEX idx_messages_created_at ON n8n_chat_histories(created_at);这段 SQL 同样以独立脚本形式保存在 messages.sql 中。从表结构看每条记录以session_id标识会话、以 JSONB 类型的message字段存放消息对象内部含type、content、可选data三个键两个索引分别加速按会话与按时间的查询——这正是 main.py 中fetch_conversation_history按session_id检索、再[::-1]反转成时间正序的依据。四、运行 Agent本地开发与 Docker 两种方式4.1 本地开发模式# 确保虚拟环境已激活 source venv/bin/activate # Linux/Mac venv\Scripts\activate # Windows # 启动 FastAPI 服务 python main.py服务启动后监听在http://localhost:8055。main.py底部的uvicorn.run(app, host0.0.0.0, port8055)指定了绑定地址与端口同时 main.py 通过 FastAPI 的lifespan钩子在应用启动时创建全局httpx.AsyncClient供web_search工具复用连接池并在关闭时优雅释放这是本地模式下搜索引擎请求高效的关键设计。4.2 Docker 与本地 AI Compose 栈集成README 提供了两种容器化接入方式方式一并入本地 AI 全家桶。将 docker-compose.yml 的 services 内容合并进 local-ai 包的 Compose 栈让 Agent 成为整个本地 AI 体系的一员。方式二独立运行但共享网络推荐。在python-local-ai-agent目录执行# 前提确保 local-ai 主栈已启动localai 网络已存在 docker compose -p localai up -d --build python-local-ai-agent该方式的优点在 docker-compose.yml 中清晰可见通过外部localai网络与其他服务互联无需改动主栈的docker-compose.yml可独立启停不影响主栈其他服务环境变量直接复用本目录.env其中SEARXNG_BASE_URL固定为容器内地址http://searxng:8080LLM_BASE_URL默认http://ollama:11434/v1并支持通过${VAR:-默认值}语法优雅降级。启动后 Agent 暴露在http://localhost:8055可与localai网络内所有服务通信Ollama 于http://ollama:11434、SearXNG 于http://searxng:8080等。需要强调的运行约束必须先启动 local-ai 主栈确保localai网络存在在本目录.env中完成环境变量配置Dockerfile 采用非 root 用户appuser运行并把pip install前置以利用镜像层缓存最终以uvicorn main:app --host 0.0.0.0 --port 8055作为容器入口命令。五、API 使用调用/invoke-python-agent端点5.1 请求格式Agent 对外暴露唯一的 POST 端点/invoke-python-agent请求体为 JSON包含两个字段chatInput用户输入的聊天文本字符串sessionId会话标识字符串用于区分不同用户的对话上下文。示例调用curl -X POST http://localhost:8055/invoke-python-agent \ -H Authorization: Bearer YOUR_BEARER_TOKEN \ -H Content-Type: application/json \ -d { chatInput: What is the latest news about AI?, sessionId: user-123 }返回结构为{output: ...}对应 main.py 中定义的ChatResponse模型。5.2 端点内部处理流程从源码看invoke_agent的完整调用链如下main.py鉴权verify_token依赖通过HTTPBearer校验请求头中的 Bearer Token与BEARER_TOKEN比对不匹配返回 401若该变量未设置或为空字符串则返回 500元数据请求分流若chatInput以### Task开头Open WebUI 元数据请求的约定前缀则交给轻量的metadata_agent直接处理不携带历史、不使用工具普通对话先调用fetch_conversation_history(sessionId, limit20)取出最近 20 条历史将其转换为 Pydantic AI 的ModelRequest/ModelResponse消息格式随后把当前用户消息写入 Supabasetype: human构造依赖并运行 Agent以全局http_client与SEARXNG_BASE_URL组装AgentDeps通过agent.run(chatInput, message_historymessages, depsdeps)触发模型推理与工具调用期间web_search工具按需访问 SearXNG回写与返回将模型输出以type: ai写入 Supabase并返回ChatResponse任何异常都会在 try/except 中被捕获错误信息同样落库并作为output返回保证前端始终能收到响应。5.3 联网搜索工具的源码级解析web_search工具见 main.py 的agent.tool装饰函数是 Agent 联网能力的核心params {q: query, format: json} response await ctx.deps.http_client.get(f{searxng_url}/search, paramsparams)其工作逻辑为向 SearXNG 的/search端点发起带q与formatjson参数的 GET 请求取结果列表中的首条[:1]源码注释写明取 Top 3 但实际截取 1 条随后尝试抓取该 URL 页面内容若抓取失败或非 200 状态则回退使用搜索结果自带的content片段截断 500 字符最终以 JSON 数组含title、url、content返回给 LLM 作为上下文。这解释了为何 Agent 能回答最新的 AI 新闻这类需要实时信息的问题。六、OpenAI 兼容性演示同一套代码适配 OpenAI 与 Ollama仓库附带交互式演示脚本 openai_compatible_demo.py用于证明OpenAI 官方 Python SDK 可以无缝对接任意 OpenAI 兼容端点包括 Ollama 的兼容层。6.1 运行方式# 确保在虚拟环境中 source venv/bin/activate # Linux/Mac python openai_compatible_demo.py脚本会按以下步骤运行枚举可用提供方配置了OPENAI_API_KEY时显示 OpenAI配置了LLM_BASE_URL时显示 Ollama 兼容模式让用户在可用提供方之间选择默认取第一个可用项依次演示三种能力基础补全basic completion、流式响应streaming、多轮对话multi-turn conversation。demo 中的 Ollama 兼容用法本质上就是一行核心代码其注释也给出了等价的直接示例from openai import OpenAI client OpenAI(base_urlhttp://localhost:11434/v1, api_keyollama)6.2 三个演示函数的要点demo_basic_completionclient.chat.completions.create(...)发送单轮请求并输出response.model与 token 用量response.usage.total_tokens展示基础补全demo_streaming设置streamTrue逐 chunk 打印delta.content展示令牌级流式输出demo_conversation手动维护messages列表把上一轮 assistant 回复追加回消息数组再进行第二轮提问展示多轮上下文如何累积。6.3 演示所需配置在.env中按需设置OllamaLLM_BASE_URL、LLM_API_KEY、LLM_CHOICE三个变量脚本会读取并作为 Ollama 提供方的 base_url、api_key 与 modelOpenAI仅需OPENAI_API_KEY。脚本内置了针对性的排障提示Ollama 需先ollama serve启动服务并ollama pull 模型名拉取模型OpenAI 需确认 API Key 有效并建议核对 base_url 拼写。七、与 Open WebUI 的集成该 Agent 天然为 Open WebUI 的 Functions 机制设计在 Open WebUI 的 Function 配置中将端点 URL 填为http://localhost:8055/invoke-python-agent并填写本项目的BEARER_TOKENOpen WebUI 发送的元数据请求以### Task前缀开头会被 main.py 自动分流给metadata_agent处理不占用对话历史与搜索工具——这与 n8n 版工作流中的「Chat message or metadata request?」条件节点行为完全一致普通聊天消息则携带sessionId进入主 Agent 流程实现带记忆、可联网的助手体验。八、常见问题排查README 给出的四类高频故障与对应排查方向Bearer Token 报错检查.env中BEARER_TOKEN是否包含引号或多余空格——main.py 的verify_token会先strip()再比对但变量值本身应保持干净数据库连接失败核对 Supabase 的 URL 与 service key 是否正确、n8n_chat_histories表是否已创建参考 messages.sqlSearXNG 连接失败确认 SearXNG 正在运行且所配 URL 可访问本地localhost:8081容器内searxng:8080Ollama 连接失败执行ollama serve启动服务并用ollama pull 模型名确认模型已就绪同时确保所选模型支持工具调用。九、二次开发指引README 提供了清晰的扩展路径结合源码可进一步明确落点全部修改集中在 main.py修改核心功能直接编辑main.py如调整fetch_conversation_history的limit参数默认 20 条以改变记忆窗口长度或修改get_model()中的默认值与retries参数调整系统提示词agent与metadata_agent定义中的system_prompt参数即为提示词入口可针对业务场景定制助手人格与行为约束新增工具仿照web_search定义带agent.tool装饰器的异步函数并通过RunContext[AgentDeps]注入共享依赖如 HTTP 客户端、第三方 API 凭据实现新的能力扩展更新依赖在 requirements.txt 中追加或调整版本后重新执行pip install -r requirements.txt若使用 Docker重新构建镜像即可。结语python-local-ai-agent用不到 300 行的核心代码串起了 Pydantic AI 编排、SearXNG 联网搜索、Supabase 记忆持久化、FastAPI 服务封装与 Open WebUI 兼容这五条完整链路是理解本地化 AI Agent 服务最小可行范式的绝佳样本。无论是作为 Open WebUI 的后端函数还是作为可独立部署、可编程控制的对话服务它都给出了开箱即用的答案——而 n8n 版工作流n8n_local_ai_agent.json则为偏好可视化编排的开发者保留了同等的选择。【免费下载链接】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），仅供参考