SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场honcho-integration

honcho-integration

智能体与模型

查看项目

更新于 10-15 14:58

技能介绍

用途

Honcho 是一个开源记忆库，用于构建有状态的智能体，可与任意模型、框架或架构配合使用。本技能用于将 Honcho 记忆集成到已有的 Python 或 TypeScript 代码库中，适用于添加 Honcho SDK、设置 peers、配置 sessions 以及访问记忆等场景。

核心概念

  • Peers：任何参与者，无论是人类还是 AI，都以相同方式表示。
  • observe_me：peer 级别的标志（PeerConfig），控制 Honcho 是否为该 peer 形成表征。通常希望 Honcho 建模用户（observe_me=True），而不建模具有确定性行为的对象（observe_me=False）。
  • observe_others：每个 peer 的 SessionPeerConfig 设置，控制该 peer 是否形成对会话中其他参与者的表征。
  • Sessions：界定 peers 之间的对话范围。
  • Messages：你输入的原始数据，Honcho 异步推理并存储为 peer 的表征。没有消息就没有推理，也就没有记忆。

智能体通过 peer.chat(query)（提出自然语言问题，获得推理答案，需要几秒实时推理）或 session.context()（近乎即时读取格式化历史与表征）访问记忆。每轮 grounding 优先使用 context()；需要推理答案时使用 chat()。

集成工作流

阶段 1：代码库探索

在询问用户之前，先探索代码库以了解：语言与框架（Python 还是 TypeScript，使用 FastAPI、Express、Next.js 等）；现有 AI/LLM 代码（搜索 OpenAI、Anthropic、LangChain 等集成）；实体结构（用户、智能体、机器人等）；会话/对话处理方式；消息流（消息发送/接收位置，请求/响应周期）。使用 Glob 和 Grep 查找包含 "openai"、"anthropic"、"llm"、"chat"、"message" 的 **/.py 或 **/.ts 文件、用户/会话模型或类型、处理聊天或对话端点的 API 路由。若代码库围绕 agent loop、tool registry、session manager 和 message bus 构建（如 nanobot、openclaw、picoclaw），阅读 references/bot-frameworks.md 获取框架特定集成指导，并查看 references/bot-frameworks/<framework>/ 中的具体参考实现。

阶段 2：访谈（必需）

探索代码库后，使用 AskUserQuestion 工具澄清集成需求。

问题集 1 - 实体与 Peers：询问哪些实体应作为 Honcho peers 被跟踪和建模，选项基于发现（如仅终端用户、用户+AI 助手、用户+多个 AI 智能体、包括第三方服务的所有参与者）。若存在多个 AI 智能体，追问是否应观察任何 AI peers。

问题集 2 - 集成模式：询问 AI 应如何访问 Honcho 的用户上下文，选项包括：工具调用（推荐，智能体通过函数调用按需查询 Honcho）、预取（每次 LLM 调用前用预定义查询获取用户上下文）、context()（在提示中包含对话历史和表征）、多种模式（针对不同用例组合方法）。

问题集 3 - 会话结构：询问对话如何映射到 Honcho sessions，选项基于应用（如每个聊天线程一个 session、每个用户一个 session、每个 session 多个用户（群聊）、自定义 session 逻辑）。

问题集 4 - 特定查询（若使用预取模式）：询问应为 AI 获取哪些用户上下文，多选，选项包括沟通风格、专业水平、目标/优先级、偏好、近期活动摘要、自定义查询。

阶段 3：实现

基于访谈回答实现集成：安装 SDK；创建 Honcho 客户端初始化（references/core-patterns.md §1）；为识别出的实体设置 peer 创建（references/core-patterns.md §2–3）；实现所选集成模式（references/agent-patterns.md）；在交换后添加消息存储（references/core-patterns.md §4）；更新任何现有对话处理器。

阶段 4：验证

若 Honcho CLI 可用，运行 honcho doctor 确认连接性，再测试集成代码；使用 honcho peer list 和 honcho peer chat 验证 peers 存在且 dialectic 端点独立于集成工作；确保所有消息交换都存储到 Honcho；验证确定性 bot peers 的 observe_me=False，AI 助手 peers 可保持观察开启；检查代码库中 workspace ID 一致；确认 API key 的环境变量已记录。

开始之前

在 https://honcho.dev/docs/changelog/introduction.md 检查最新 SDK 版本。Python SDK：honcho-ai；TypeScript SDK：@honcho-ai/sdk。获取 API key：请用户从 https://app.honcho.dev 获取 Honcho API key 并添加到环境。

可选但推荐使用 CLI 验证。若用户已安装 Honcho CLI（uv install honcho-cli），可在编写任何集成代码前验证设置：

honcho init # persist API key + URL to ~/.honcho/config.json honcho doctor # verify connectivity, config, workspace health honcho peer chat # test the dialectic endpoint interactively

这是在调试 SDK 代码前确认 API key 和 URL 正确的最快方式。

安装

Python（使用 uv）：

uv add honcho-ai

TypeScript（使用 bun）：

bun add @honcho-ai/sdk

Python 中 SDK 默认同步（带 .aio 异步命名空间），TypeScript 中仅异步——将客户端与框架匹配。完整的同步/异步指导及基础 client/peer/session/message 代码见 references/core-patterns.md。

集成清单

将 Honcho 集成到已有代码库时：用 uv add honcho-ai（Python）或 bun add @honcho-ai/sdk（TypeScript）安装 SDK；设置 HONCHO_API_KEY 环境变量；用单一 workspace ID 初始化 Honcho 客户端；为所有实体（用户和 AI 助手）创建 peers；为确定性 bot peers 设置 observe_me=False（AI 助手可选——保持观察开启也可以）；配置 sessions 及适当的 peer 观察设置；选择集成模式（智能体系统用工具调用模式，简单集成用预取模式，对话历史用 context()）；每次交换后存储消息以构建用户模型；（可选）在测试集成代码前运行 honcho doctor 验证连接性；（可选）使用 honcho peer chat 独立测试 dialectic 查询。

常见错误

  • 多个 workspaces：每个应用使用一个 workspace。
  • 忘记 AI peers：不仅为用户，也为 AI 助手创建 peers。
  • 建模 bots：为确定性 bots 设置 observe_me=False（脚本化输出，没有可建模的有意义内容）。对于 AI 助手，保持观察开启也可以；当你只关心用户时，关闭它是可选优化。
  • 不存储消息：始终调用 add_messages() 以馈送 Honcho 的推理引擎。
  • 阻塞处理：消息异步处理——不要轮询或等待推理完成再继续。

资源

文档（LLM 友好索引）：https://honcho.dev/docs/llms.txt 最新 SDK 版本：https://honcho.dev/docs/changelog/introduction.md API 参考：https://honcho.dev/docs/v3/api-reference/introduction.md 提示：在任何 Honcho 文档 URL 后附加 .md 可获取原始 Markdown 版本。