LocalAI 内置 Agent 平台实战：从 AgentPool 架构、知识库存储到 SSE 流式 API 全解析

LocalAI 内置了一套由 LocalAGI 驱动的原生 Agent 平台：智能体作为 LocalAI 进程内的一等公民运行，可自主推理、调用工具、维护记忆并对接外部服务，且无需额外安装任何组件。本文围绕 LocalAI 官方文档 agents.md 展开，系统讲解 Agent 的创建与导入、完整的环境变量配置体系（含 PostgreSQL 向量库与连接安全超时）、技能（Skills）系统、REST/SSE API 全集，以及生成文件的受限输出目录机制，并结合 agent_pool.go 等源码剖析其"自引用推理环"的底层实现。

一、Overview：Agent 系统能提供什么

LocalAI 的 Agent 系统（Agent Pool）在单进程内提供以下完整能力：

• 自主智能体（Autonomous agents）：可配置目标、人格（system prompt）与能力集；
• 工具/动作支持（Tool/Action support）：智能体可执行动作，如网络搜索、代码执行、API 调用等；
• 知识库（RAG）：每个 agent 拥有独立的 collection，支持文档上传、切块（chunking）与语义检索；
• 技能系统（Skills）：可复用的技能定义（名称、描述、内容、可选资源文件），支持基于 git 的技能仓库；
• SSE 流式：通过 Server-Sent Events 与智能体实时对话；
• 导入/导出：以 JSON 文件形式分享 agent 配置；
• Agent Hub：从 agenthub.localai.io 浏览并下载现成 agent；
• Web UI：完整的智能体创建、编辑、对话与监控界面。

值得注意的是，LocalAGI 是直接嵌入 LocalAI 的（embedded），没有独立的安装或运行步骤。这一点在源码中得到了印证：agent_pool.go 中的 localAGICore 结构体直接持有 state.AgentPool（LocalAGI 核心）与 skills.Service，并在 NewAgentPoolService 中随 LocalAI 服务一起初始化。

快速开始：创建与导入 Agent

Agent 功能默认启用。如需禁用，设置环境变量：

LOCALAI_DISABLE_AGENTS=true

该开关对应 run.go 中 DisableAgents 字段（env:"LOCALAI_DISABLE_AGENTS" default:"false"）。

创建 Agent 的步骤（Web UI）：

1. 打开 Web UI 中的 Agents 页面；
2. 点击 Create Agent，或从 Agent Hub 导入现成配置；
3. 配置 agent 的名称、模型、system prompt 与 actions；
4. 保存并开始对话。

导入 Agent（JSON 文件）：

1. 从 Agent Hub 下载 agent 配置，或从另一个 LocalAI 实例导出；
2. 在 Agents 页面点击 Import；
3. 选择 JSON 文件——会先进入编辑表单，可在保存前审查并调整配置；
4. 点击 Create Agent 完成导入。

二、配置体系：全部环境变量的完整清单

所有 Agent 相关设置均可通过环境变量配置。下表完整继承自官方文档，默认值已逐一与 run.go 及 agent.go 中的字段定义核对：

变量	默认值	说明
LOCALAI_DISABLE_AGENTS	false	完全禁用 agent pool 功能
LOCALAI_AGENT_POOL_API_URL	（自引用）	agent 默认调用的 API URL。默认回调 LocalAI 自身 API（http://127.0.0.1:<port>）。设为外部地址可指向其他 LLM 提供商
LOCALAI_AGENT_POOL_API_KEY	（LocalAI key）	agent 默认 API key。默认取第一个 LocalAI API key；使用外部提供商时需设置
LOCALAI_AGENT_POOL_DEFAULT_MODEL	（空）	新 agent 的默认 LLM 模型
LOCALAI_AGENT_POOL_MULTIMODAL_MODEL	（空）	agent 默认多模态（视觉）模型
LOCALAI_AGENT_POOL_TRANSCRIPTION_MODEL	（空）	agent 默认转写（语音转文本）模型
LOCALAI_AGENT_POOL_TRANSCRIPTION_LANGUAGE	（空）	agent 默认转写语言
LOCALAI_AGENT_POOL_TTS_MODEL	（空）	agent 默认 TTS（文本转语音）模型
LOCALAI_AGENT_POOL_STATE_DIR	（data path）	agent 状态持久化目录。默认取 LOCALAI_DATA_PATH，否则回退到 LOCALAI_CONFIG_DIR
LOCALAI_AGENT_POOL_TIMEOUT	5m	agent 操作的默认超时
LOCALAI_AGENT_POOL_ENABLE_SKILLS	false	启用技能服务
LOCALAI_AGENT_POOL_VECTOR_ENGINE	chromem	知识库向量引擎（chromem 或 postgres）
LOCALAI_AGENT_POOL_EMBEDDING_MODEL	granite-embedding-107m-multilingual	知识库 embedding 模型
LOCALAI_AGENT_POOL_CUSTOM_ACTIONS_DIR	（空）	自定义 action 插件目录
LOCALAI_AGENT_POOL_DATABASE_URL	（空）	PostgreSQL 连接串（向量引擎为 postgres 时必填）
LOCALAI_AGENT_POOL_MAX_CHUNKING_SIZE	400	文档入库时的最大 chunk 大小
LOCALAI_AGENT_POOL_CHUNK_OVERLAP	0	相邻 chunk 之间的重叠量
LOCALAI_AGENT_POOL_ENABLE_LOGS	false	启用详细 agent 日志
LOCALAI_AGENT_POOL_COLLECTION_DB_PATH	（空）	collections 数据库的自定义路径
LOCALAI_AGENT_HUB_URL	https://agenthub.localai.io	Agent Hub 地址（显示在 UI 中）

从源码看，自引用 API URL 的解析逻辑在 agent_pool.go 的 Start 方法 中：当 cfg.APIURL 为空时，服务从 LocalAI 自身的 APIAddress 中解析端口，拼出 http://127.0.0.1:<port> 作为 agent 的 LLM 调用地址；APIKey 为空时则自动取 ApiKeys[0]。状态目录的解析同样在此完成，按 STATE_DIR → DataPath → DynamicConfigsDir → "agents" 的优先级回退（cmp.Or(cfg.StateDir, s.appConfig.DataPath, s.appConfig.DynamicConfigsDir, "agents")），与文档描述的默认行为完全一致。

知识库存储：chromem 与 PostgreSQL 双引擎

默认情况下知识库使用 chromem——一个进程内向量化存储，零外部依赖。对于更大规模的生产知识库，可切换到 PostgreSQL + pgvector：

LOCALAI_AGENT_POOL_VECTOR_ENGINE=postgres
LOCALAI_AGENT_POOL_DATABASE_URL=postgresql://localrecall:localrecall@postgres:5432/localrecall?sslmode=disable

PostgreSQL 镜像 quay.io/mudler/localrecall:v0.5.2-postgresql 已预装 pgvector，开箱即用。

向量引擎、embedding 模型与切块参数统一经由 buildCollectionsConfig 组装为 collections.Config 并注入 NewInProcessBackend，即 VectorEngine、EmbeddingModel、MaxChunkingSize、ChunkOverlap、DatabaseURL 等字段直接对应上表的环境变量。

PostgreSQL 连接安全超时

嵌入的向量存储会设置逐连接超时，确保单个卡死或损坏的索引永远不会无限期持有锁、拖垮所有其他 collection 操作。安全默认值自动生效，仅需在覆盖时设置：

变量	默认值	说明
POSTGRES_LOCK_TIMEOUT	30s	限定语句等待获取锁的时间，使排队语句快速失败而非堆积。设 0/off 禁用
POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT	300s	回收被抛弃的、本会持续占用锁的事务。设 0/off 禁用
POSTGRES_STATEMENT_TIMEOUT	（未设置）	限定语句总运行时间，自动中止卡死查询。默认关闭，因为大型向量索引构建可能超过任何固定上限；索引构建被豁免，因此开启是安全的

这三个超时由嵌入的向量存储直接从 LocalAI 进程环境读取（与 DATABASE_URL、HYBRID_SEARCH_* 同理）。

Docker Compose 部署示例

基础版（内存向量存储）：

services:
  localai:
    image: localai/localai:latest
    ports:
      - 8080:8080
    environment:
      - MODELS_PATH=/models
      - LOCALAI_DATA_PATH=/data
      - LOCALAI_AGENT_POOL_DEFAULT_MODEL=hermes-3-llama3.1-8b
      - LOCALAI_AGENT_POOL_EMBEDDING_MODEL=granite-embedding-107m-multilingual
      - LOCALAI_AGENT_POOL_ENABLE_SKILLS=true
      - LOCALAI_AGENT_POOL_ENABLE_LOGS=true
    volumes:
      - models:/models
      - localai_data:/data
      - localai_config:/etc/localai
volumes:
  models:
  localai_data:
  localai_config:

PostgreSQL 持久化知识库版：

services:
  localai:
    image: localai/localai:latest
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - 8080:8080
    environment:
      - MODELS_PATH=/models
      - LOCALAI_AGENT_POOL_DEFAULT_MODEL=hermes-3-llama3.1-8b
      - LOCALAI_AGENT_POOL_EMBEDDING_MODEL=granite-embedding-107m-multilingual
      - LOCALAI_AGENT_POOL_ENABLE_SKILLS=true
      - LOCALAI_AGENT_POOL_ENABLE_LOGS=true
      # PostgreSQL-backed knowledge base
      - LOCALAI_AGENT_POOL_VECTOR_ENGINE=postgres
      - LOCALAI_AGENT_POOL_DATABASE_URL=postgresql://localrecall:localrecall@postgres:5432/localrecall?sslmode=disable
    volumes:
      - models:/models
      - localai_config:/etc/localai

  postgres:
    image: quay.io/mudler/localrecall:v0.5.2-postgresql
    environment:
      - POSTGRES_DB=localrecall
      - POSTGRES_USER=localrecall
      - POSTGRES_PASSWORD=localrecall
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U localrecall"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  models:
  localai_config:
  postgres_data:

三、单个 Agent 的配置项

每个 agent 拥有独立的行为配置，关键设置包括：

• Name — agent 的唯一标识符；
• Model — 该 agent 用于推理的 LLM 模型；
• System Prompt — 定义 agent 的人格与指令；
• Actions — agent 可使用的工具（网络搜索、代码执行等），完整内置动作目录见 agent-actions.md；
• Connectors — 外部集成（Slack、Discord 等）；
• Knowledge Base — 用于 RAG 的文档集合；
• MCP Servers — Model Context Protocol 服务器，提供额外的工具访问。

Pool 级默认值（API URL、API key、模型）通过环境变量设置；而单个 agent 可在自己的配置中逐项覆盖这些默认值，从而让不同 agent 分别使用不同的 LLM 提供商（OpenAI、其他 LocalAI 实例等）。这一点在 agent.go 的 applyOverrides 中有直接体现：CLI 启动独立 agent 时，只有当 agent 配置本身为空时才套用 pool 级的 APIURL/APIKey/各模型默认值——即 agent 自身配置优先。

此外，LocalAI 还支持脱离完整服务器独立运行单个 agent：local-ai agent run 子命令可从 pool.json 注册表按名称加载，或用 -c 指定 JSON 配置文件，配合 -p 以前台模式发送单条 prompt 并打印结果后退出（见 AgentRunCMD）；local-ai agent list 则列出注册表中的所有 agent 及其模型与描述。

四、Skills 技能系统

技能（Skills）是可复用的指令集——由名称、描述、技能内容组成，可选附带资源文件——agent 在工作时随时可以调用。技能可以直接编写，也可以从 git 技能仓库导入，使一组技能跨 agent、跨机器共享。

注意：技能默认禁用。只有以 LOCALAI_AGENT_POOL_ENABLE_SKILLS=true 启动 LocalAI 时技能服务才运行；默认的 false 下，Skills UI 与 /api/agents/skills 端点均不活跃，导入的 agent 若期望某个技能将找不到它。

启用技能

LOCALAI_AGENT_POOL_ENABLE_SKILLS=true local-ai run

在 Docker 中将同一变量加入容器环境即可。

创建技能

启用技能后，打开 Web 界面的 Agents 区域进入 Skills 面板。创建技能需要提供：

• name（引用该技能的标识）；
• description（技能用途）；
• content（技能生效时 agent 遵循的指令）；
• 可选的资源文件。

同样的操作可通过 REST 完成：

curl http://localhost:8080/api/agents/skills \
  -H "Content-Type: application/json" \
  -d '{
    "name": "changelog-writer",
    "description": "Write a release changelog from a list of merged PRs",
    "content": "When asked for a changelog, group the PRs by type (feature, fix, docs) and write one concise bullet per PR."
  }'

也可以通过 POST /api/agents/skills/import 导入技能归档，或添加 git 技能仓库让其中的技能被拉取进来。

使用技能

技能存在且技能服务启用后，agent 即可在推理中使用它。列出当前可用技能：

curl http://localhost:8080/api/agents/skills

如果预期中的技能缺失，请确认 LocalAI 是以 LOCALAI_AGENT_POOL_ENABLE_SKILLS=true 启动的。

从源码结构看，技能服务在 startLocalAGI 中以 skills.NewService(stateDir) 创建（基于文件系统的存储），并传入 state.NewAgentPool 构造函数成为 agent 运行时的一部分；路由侧则由 skillsMw 中间件把 /api/agents/skills 组与 /api/agents/git-repos 组都挂到技能开关之后（见 routes/agents.go），与文档"默认不活跃"的描述相互印证。

五、REST API 端点全集

所有 agent 端点统一挂载在 /api/agents/ 下（路由定义见 core/http/routes/agents.go）。

Agent 管理

Method	Path	说明
GET	/api/agents	列出所有 agent 及其状态
POST	/api/agents	创建新 agent
GET	/api/agents/:name	获取 agent 信息
PUT	/api/agents/:name	更新 agent 配置
DELETE	/api/agents/:name	删除 agent
GET	/api/agents/:name/config	获取 agent 配置
PUT	/api/agents/:name/pause	暂停 agent
PUT	/api/agents/:name/resume	恢复已暂停的 agent
GET	/api/agents/:name/status	获取 agent 状态与可观测指标
POST	/api/agents/:name/chat	向 agent 发送消息
GET	/api/agents/:name/sse	SSE 流，获取 agent 实时事件
GET	/api/agents/:name/export	导出 agent 配置为 JSON
POST	/api/agents/import	从 JSON 导入 agent
GET	/api/agents/:name/files?path=...	从 outputs 目录分发已生成文件
GET	/api/agents/config/metadata	获取动态配置表单元数据（含 outputsDir）

Skills

Method	Path	说明
GET	/api/agents/skills	列出所有技能
POST	/api/agents/skills	创建技能
GET	/api/agents/skills/:name	获取技能
PUT	/api/agents/skills/:name	更新技能
DELETE	/api/agents/skills/:name	删除技能
GET	/api/agents/skills/search	搜索技能
GET	/api/agents/skills/export/*	导出技能
POST	/api/agents/skills/import	导入技能

Collections（知识库）

Method	Path	说明
GET	/api/agents/collections	列出 collections
POST	/api/agents/collections	创建 collection
POST	/api/agents/collections/:name/upload	上传文档
GET	/api/agents/collections/:name/entries	列出条目
POST	/api/agents/collections/:name/search	搜索 collection
POST	/api/agents/collections/:name/reset	重置 collection

Actions

Method	Path	说明
GET	/api/agents/actions	列出可用动作
POST	/api/agents/actions/:name/definition	获取动作定义
POST	/api/agents/actions/:name/run	执行动作

六、通过 Responses API 调用 Agent

Agent 可以通过标准的 /v1/responses 端点（OpenAI Responses API）以编程方式调用——只需把 agent 名称作为 model 字段：

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-agent",
    "input": "What is the weather today?"
  }'

返回标准的 Responses API 响应：

{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "my-agent",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The agent's response..."
        }
      ]
    }
  ]
}

input 也支持结构化消息数组：

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-agent",
    "input": [
      {"role": "user", "content": "Summarize the latest news about AI"}
    ]
  }'

路由规则是：当 model 名称命中某个 agent 时，请求被路由到 agent pool；若无匹配则回落到常规基于模型名的推理管线。这使得同一端点既服务普通模型推理又服务 agent 调用，对调用方完全透明。

七、SSE 流式对话

实时流式响应使用 chat 端点配合 SSE。

发送消息：

curl -X POST http://localhost:8080/api/agents/my-agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the weather today?"}'

监听实时事件：

curl -N http://localhost:8080/api/agents/my-agent/sse

SSE 流会发出以下事件类型：

• json_message — agent/user 消息；
• json_message_status — 处理状态更新（processing / completed）；
• status — 系统消息（推理步骤、动作结果）；
• json_error — 错误通知。

事件发布的抽象接口见 AgentEventBridge：PublishMessage / PublishStatus / PublishStreamEvent 分别对应上述事件类型，且支持按 key 注册与注销取消函数（RegisterCancel / DeregisterCancel），实现长任务的优雅中断。

八、生成文件与 Outputs 目录

部分 agent 动作（图像生成、PDF 创建、音频合成）会产出文件。这些文件由 LocalAI 通过一个受限的 outputs 目录统一管理。

工作机制

1. 动作把文件写入其配置的 outputDir（可以是文件系统上的任意路径）；
2. 每次 agent 响应后，LocalAI 自动把生成的文件复制到 {stateDir}/outputs/；
3. 文件分发端点（/api/agents/:name/files?path=...）只从该 outputs 目录分发文件；
4. agent 响应元数据中的文件路径被重写，指向复制后的文件。

这一设计保证了：

• 动作可以把文件写到任何需要的目录；
• 文件分发端点被限定在单一可信目录内——不存在任意文件系统访问；
• 符号链接穿越（symlink traversal）通过 filepath.EvalSymlinks 校验被阻断。

源码印证：outputsDir 的初始化在 startLocalAGI 中，即 filepath.Join(stateDir, "outputs") 并以 0750 权限创建；多用户场景下还会进一步按用户划分子目录（见 agent_pool.go 的 filepath.Join(s.outputsDir, userID)）。

访问生成的文件

curl http://localhost:8080/api/agents/my-agent/files?path=/path/to/outputs/image.png

path 参数必须指向 outputs 目录内的文件；请求该目录之外的文件会被拒绝并返回 403 Forbidden。

SSE 消息中的元数据

当 agent 动作产出文件时，SSE 的 json_message 事件会携带 metadata 字段：

{
  "id": "msg-123-agent",
  "sender": "agent",
  "content": "Here is the image you requested.",
  "metadata": {
    "images_url": ["http://localhost:8080/api/agents/my-agent/files?path=..."],
    "pdf_paths": ["/path/to/outputs/document.pdf"],
    "songs_paths": ["/path/to/outputs/song.mp3"]
  },
  "timestamp": "2025-01-01T00:00:00Z"
}

Web UI 利用这些元数据显示内联资源卡片（图片、PDF、音频播放器），并可在画布面板中打开文件。

查询 outputs 目录

outputs 目录位于 {stateDir}/outputs/，其中 stateDir 默认取 LOCALAI_AGENT_POOL_STATE_DIR（或回退到 LOCALAI_DATA_PATH / LOCALAI_CONFIG_DIR）。可通过以下端点查询当前路径：

curl http://localhost:8080/api/agents/config/metadata

返回的 JSON 对象中包含 outputsDir 字段。

九、架构剖析：进程内的自引用推理环

Agent 在 LocalAI 进程内运行。默认情况下，每个 agent 回调 LocalAI 自身的 API（http://127.0.0.1:<port>/v1/chat/completions）完成 LLM 推理。这带来几个直接的好处：

• 零外部依赖——一切都在单个二进制中运行；
• agent 直接使用 LocalAI 中已加载的模型；
• 逐 agent 的覆盖机制允许把单个 agent 指向外部提供商；
• agent 状态持久化到磁盘并在重启后恢复（注册表为 stateDir/pool.json）。

完整的调用链如下：

User → POST /api/agents/:name/chat → LocalAI
  → AgentPool → Agent reasoning loop
    → POST /v1/chat/completions (self-referencing)
      → LocalAI model inference → response
        → SSE events → GET /api/agents/:name/sse → UI

从源码结构看，AgentPoolService（agent_pool.go）内部还区分了两种运行形态：

• Standalone 模式：走 startLocalAGI，创建完整的 LocalAGI state.AgentPool，附带 in-process collections 后端与 RAG provider，agent 状态落盘到 pool.json；
• Distributed 模式：当注入了 NATS 客户端时走 startDistributed，agent 执行变为无状态，经由 NATS dispatcher 分发到 worker，agent 配置与技能元数据改存 PostgreSQL（agents.AgentStore / distributed.SkillStore），前端实例还运行一个基于 advisory lock 的后台 agent 调度器。

两种模式下，outputs 目录、skills 服务与 collections 后端的初始化逻辑保持一致，因此上文介绍的 API 与配置在分布式部署中同样适用。

小结

LocalAI 的 Agent 平台把 LocalAGI 完整嵌入主进程：agent 默认回调自身 API 形成"自引用推理环"，通过 LOCALAI_AGENT_POOL_* 一族环境变量即可配置模型、知识库引擎（chromem/PostgreSQL+pgvector）、技能与日志；REST 端点覆盖管理、技能、知识库与动作四大类，SSE 提供实时事件流，生成文件则被收敛在受限的 outputs 目录中保障安全。对希望深入了解实现的读者，建议从 core/services/agentpool/agent_pool.go、core/http/routes/agents.go 与 core/cli/agent.go 三个入口继续阅读源码，并参考 first-agent.md 完成从空白 Agents 页面到第一个可用 agent 的动手练习。