IntentKit 快速入门用 Docker Compose 启动 Agent 集群 API 并通过 REST 接口创建与交互【免费下载链接】intentkitIntentKit is an open-source, self-hosted cloud agent cluster that manages a collaborative team of AI agents for you.项目地址: https://gitcode.com/GitHub_Trending/int/intentkit本篇指南以 docs/content/en/guide/getting-started.md 为核心骨架讲解 IntentKit 的自托管快速起步流程使用 Docker Compose或 Docker Swarm拉起 API 服务器、通过http://localhost:8000/redoc探索全部端点、创建 Agent 配置并调用 API 与之对话。读完本文你将掌握从零启动整套云 Agent 集群基础设施数据库、对象存储、Redis、API、自动执行器、调度器与消息通道的完整操作路径并能够用 curl 完成第一个 Agent 的创建、聊天与查询。一、快速起步三步总览原文档给出的起步路径非常精简只有三步这是整个部署流程的主干使用 Docker Compose 或 Docker Swarm 启动 API 服务器。在http://localhost:8000/redoc浏览可用的 API 端点。创建 Agent 配置并通过 API 与它交互。下面各节将围绕这三步逐一展开并结合仓库中的实际配置文件与源码说明每一步背后的实现细节、可调整参数与常见坑位。二、第一步启动 API 服务器2.1 准备环境变量文件仓库根目录提供了完整的配置模板 .env.example启动前先把它复制为.envcp .env.example .env本地开发模式下最低限度的必填配置只有LLM Provider 的 API Key至少一个例如 OpenRouter、OpenAI 或 DeepSeek# LLM Providers, at least one is required OPENROUTER_API_KEYsk-xxx # 或 OPENAI_API_KEYsk-xxx # 或 DEEPSEEK_API_KEYsk-xxx其余配置在本地 Docker Compose 环境下都有合理的默认值或留空即可ENVlocal、DEBUGtrue本地开发模式标记APP_DOMAIN、TLS_EMAIL仅线上部署时需要用于 Caddy 域名与 Lets Encrypt 证书本地留空DB_HOST等数据库配置如果使用 compose 文件内的数据库留空即可因为 docker-compose.yml 会通过环境变量注入DB_HOSTdb、DB_PORT5432等连接信息AWS_S3_*本地开发时同样由 compose 注入 rustfsS3 兼容对象存储的连接参数。2.2 本地开发docker compose up仓库根目录的 docker-compose.yml 是面向本地开发的一键编排文件共定义了 8 个服务服务镜像 / 构建方式端口职责dbpostgres:18.1-trixie15432:5432主数据库存放 Agent 配置、聊天记录、信用账户等rustfsrustfs/rustfs:latest9000/9001S3 兼容对象存储存放图片等静态资源redisredis:8.4-bookworm内部缓存与消息中间件api本地构建含--reload8000:8000FastAPI 服务唯一对外暴露的核心入口autonomous本地构建内部自动执行引擎负责自主运行任务scheduler本地构建内部定时调度器frontend./frontend的Dockerfile.dev3000:3000Next.js 前端控制台telegram/wechat./integrations构建内部Telegram / 微信消息通道集成启动命令docker compose up -d关键设计点对应原文档“Start the API server”的完整含义依赖就绪控制api服务通过depends_on的condition: service_healthy等待db与redis健康检查通过后才启动autonomous和scheduler又等待api就绪避免启动竞态开发热重载api的启动命令是uvicorn app.api:app --host 0.0.0.0 --port 8000 --reload同时以 volume 方式挂载./intentkit、./app、./public_agents与./.env改代码即时生效健康检查API 自身通过GET /health做健康检查见 docker-compose.ymlautonomous/scheduler则调用 scripts/check_heartbeat.py 验证心跳。启动完成后可以验证服务状态docker compose ps curl http://localhost:8000/health2.3 API 启动时做了什么从源码看API 进程并非只挂一个 HTTP 服务启动阶段还完成了一系列初始化工作。入口位于 app/api.py其lifespan上下文管理器依次执行初始化数据库await init_db(**config.db)并自动迁移表结构DB_AUTO_MIGRATEtrue时初始化 Redisinit_redis(...)建立连接池初始化 S3 Bucket调用ensure_bucket_exists_and_public()实现在 intentkit/clients/s3_setup.py自动创建static桶并设置为公开创建系统用户与团队ensure_system_user_and_team()会在数据库中确保存在system用户、system团队及其 OWNER 成员记录见 app/api.py同步公共 Agent从 public_agents/base 下的 YAML 文件批量同步内置公共 Agentsync_public_agents()。因此“启动 API 服务器”实质上是把整套运行时依赖DB Redis 对象存储 预置数据一并初始化好后续所有 Agent 操作都建立在这一套基础设施之上。2.4 生产部署Compose 镜像版与 Swarm原文档提到 “Docker Compose or Swarm” 两种方式仓库对生产场景提供了两套独立编排单机生产Compose Caddydeployment/docker-compose.yml 使用ghcr.io/crestalnetwork/intentkit:latest等预构建镜像并通过 deployment/caddy-entrypoint.sh 注入 Caddy 反向代理对外暴露 80/443由APP_DOMAIN、TLS_EMAIL、BASIC_AUTH_USER/BASIC_AUTH_PASSWORD控制域名、HTTPS 证书与基础认证。注意生产版不再挂载源码、不带--reload且 S3 的 CDN URL 直接指向 rustfs 或你的对象存储集群生产Docker Swarmdeployment/docker-stack.yml 是docker stack deploy专用文件为每个服务声明了deploy段api副本数 2、滚动更新update_configparallelism: 1、order: start-first有状态服务db/redis/rustfs通过placement.constraints约束到打上node.labels.stateful true标签的节点。# 单机生产先设置域名等环境变量再启动 APP_DOMAINagents.example.com TLS_EMAILyouexample.com docker compose -f deployment/docker-compose.yml up -d # Swarm 集群初始化 swarm 并给有状态节点打标签后部署 docker node update --label-add statefultrue node docker stack deploy -c deployment/docker-stack.yml intentkit2.5 Dockerfile 构建细节如果选择源码构建根目录 Dockerfile其采用经典的两阶段构建builder 阶段基于python:3.13-slim先安装uv用uv sync --locked --group app --no-install-project安装依赖排除 pytest、ruff 等 dev 工具再安装项目本体runtime 阶段只复制虚拟环境与intentkit、app、scripts、public_agents目录并安装libpq5、Pango/Cairo 字体等运行依赖用于图片生成与 PDF 渲染默认命令为uvicorn app.api:app --host 0.0.0.0 --port 80。RELEASE构建参数${RELEASE:-latest}会写入镜像环境变量作为 API 的版本标识。三、第二步在 redoc 中探索端点API 服务启动后FastAPI 会自动生成两份交互式文档ReDoc原文档指定http://localhost:8000/redocSwagger UIhttp://localhost:8000/docsReDoc 页面会列出全部注册路由。从 app/api.py 的include_router调用可以看出本地开发模式下挂载了以下路由组路由前缀 / 分组来源模块主要能力/agentsapp/local/agent.pyAgent 的创建、覆盖、更新、查询、部署/agents/{aid}/chatsapp/local/chat.py聊天线程的增删改查与消息收发SSE 流式/autonomousapp/local/autonomous.py自主执行任务管理/leadapp/local/lead.py线索Lead挖掘/contentapp/local/content.py内容生成/metadataapp/local/metadata.py元数据查询/schemaapp/local/schema.py工具 schema 同步/wechatapp/local/wechat.py微信通道管理/publicapp/local/public.py公开 Agent 浏览/healthapp/common/health.py健康检查注意本地路由有意不做鉴权源码注释明确说明它们“为本地开发调试而设计生产环境不应暴露到公网”。因此 ReDoc 适合本地体验全部端点生产环境请通过 Caddy Basic Auth 或前文的基础认证保护。四、第三步创建 Agent 配置并通过 API 交互4.1 创建 AgentPOST /agents创建 Agent 的端点在 app/local/agent.py 中实现POST /agents状态码 201请求体为AgentUpdate实际转换为AgentCreate校验本地模式下owner与team_id自动固定为system。一个最小化的创建请求curl 示例curl -X POST http://localhost:8000/agents \ -H Content-Type: application/json \ -d { name: my-trading-assistant, system_prompt: You are a helpful crypto trading assistant., model: openrouter/anthropic/claude-3.5-sonnet }端点内部的处理链路对应 intentkit/core/agent/management.py 中的create_agentAgentCreate.model_validate(agent)完成请求体校验create_agent()落库并返回最新 Agent 与关联的 AgentDatainvalidate_lead_cache()使线索缓存失效若未提供头像backfill_agent_avatar会作为后台任务异步补齐响应体由AgentResponse.from_agent()生成并附带ETag 头用于条件更新。关于请求体字段intentkit/models/agent/agent.py 中class Agent(AgentCreate, AgentPublicInfo)表明 Agent 同时继承创建模型与公开信息模型常用字段包括nameAgent 名称必填system_prompt系统提示词决定 Agent 行为modelLLM 模型标识与.env中配置的 Provider 对应tools启用的工具集白名单仓库 intentkit/tools 下按目录组织了几十个工具集如erc20、uniswap、twitter等picture头像图可为空由后台任务生成slug对外别名仓库另有 scripts/migrate_slug.sql 迁移支撑。4.2 查询与覆盖 AgentGET /agents/{agent_id}按 ID 或 slug 查询支持get_agent_by_id_or_slugPUT /agents/{agent_id}覆盖式更新未提供的字段会重置为默认值对应override_agent见 app/local/agent.pyPATCH /agents/{agent_id}局部更新patch_agent。所有写操作响应同样携带 ETag便于客户端做缓存与并发控制。4.3 与 Agent 对话创建线程并发消息聊天功能位于 app/local/chat.py本地模式所有user_id固定为systemLOCAL_USER_ID。典型调用序列1. 创建聊天线程curl -X POST http://localhost:8000/agents/{aid}/chats \ -H Content-Type: application/json \ -d {first_message: Hello, analyze BTC price trend}线程 ID 使用XIDepyxid库生成若首条消息符合摘要条件会自动异步更新线程摘要should_summarize_first_message/update_chat_summary_from_first_message。2. 发送消息流式curl -N -X POST http://localhost:8000/agents/{aid}/chats/{chat_id}/messages \ -H Content-Type: application/json \ -d {content: Hello, author_type: user}消息发送走execute_agent/stream_agent实现在 intentkit/core/engine/stream.py返回SSE 流式响应Agent 在执行过程中会按事件逐步返回思考、工具调用与最终回复长任务通过task_registry注册可被取消。3. 拉取历史消息curl http://localhost:8000/agents/{aid}/chats/{chat_id}/messages?limit20cursorxxx历史消息接口采用基于游标的分页limit取值范围 1–100默认 20返回has_more与next_cursor字段客户端用next_cursor继续翻页对应 app/local/chat.py。4.4 验证与测试仓库提供了覆盖上述链路的自动化测试可作为“快速起步后如何验证”的补充参考API 层测试tests/api/team团队模式下各端点的集成测试引擎对话测试tests/bdd/test_engine_conversation.pyAgent 管理测试tests/bdd/test_agent_management.py 与 tests/core/test_agent_management.py聊天核心测试tests/core/test_chat.py。本地运行测试uv run pytest tests/core/test_chat.py tests/bdd/test_agent_management.py五、常见问题与进阶指引健康检查失败先确认db/redis健康后再排查apiautonomous/scheduler依赖 API 就绪且通过心跳脚本检查若日志提示 heartbeat 超时可运行 scripts/check_heartbeat.py 手动诊断图片 / 静态资源 404确认 rustfs 服务正常且AWS_S3_CDN_URL指向正确本地为http://localhost:9000/static想了解全部环境变量完整清单见 .env.example涵盖 LLM Provider、数据库、Redis、S3、Supabase Auth、Telegram/微信/XMTP 通道、Twitter OAuth2、Web3 钱包CDP/Privy/Safe与可观测性Sentry/Langfuse/LangSmith等配置进阶阅读部署相关细节可继续阅读 docs/content/en/deployment 下的部署文档进阶能力文档位于 docs/content/en/advanced。六、小结回到原文档的三步骨架用docker compose up -d或生产环境的deployment/docker-compose.yml/docker-stack.yml启动 API 服务器 → 打开http://localhost:8000/redoc浏览全部端点 → 通过POST /agents创建 Agent 配置并用聊天接口交互。整个过程背后有 FastAPI 启动期的自动初始化数据库、Redis、S3、公共 Agent 同步、健康检查依赖编排与本地免鉴权路由设计作为支撑。按照本文步骤操作你就能在本地拥有一个可运行的 IntentKit Agent 集群并以此为基础继续探索工具集、自主执行与多通道集成能力。【免费下载链接】intentkitIntentKit is an open-source, self-hosted cloud agent cluster that manages a collaborative team of AI agents for you.项目地址: https://gitcode.com/GitHub_Trending/int/intentkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考