framerslab/agentos · 上手攻略

是什么

AgentOS 是一个开源 TypeScript AI Agent 框架，主打三件事：①带神经科学背景的"认知记忆"（8 种机制：艾宾浩斯衰减、提取诱发遗忘、再固化、来源置信度衰减等）；②运行时工具锻造（runtime tool forging）——Agent 现场写 TypeScript + Zod schema 的函数，由独立 LLM judge 审核后在加固的 node:vm 沙箱里跑；③可选的 HEXACO 人格向量（6 维人格特质）调节检索、路由与决策。除主包外还有 5 个配套包：100+ 一方扩展（@framers/agentos-extensions）、88 个 SKILL.md 技能（@framers/agentos-skills）、基准测试 harness（agentos-bench，MIT）以及 SQL 存储适配器。

⚠️ 主仓 README 把"LongMemEval-S 85.6% / LongMemEval-M 70.2%"作为差异点高调宣传，需注意：①这是项目自报基准，未与其他家在同一硬件/预算下复测；②gpt-4o reader + gpt-4o-2024-08-06 judge 是特定版本的组合，自报值不等同于最新 openai 模型可复现。

解决什么问题

Agent 落到生产里通常死在三个点上：长对话丢上下文（LongMemEval 类基准就是量化这一痛点）；工具集写死、缺工具时要人工加（"运行时锻造"是直接回应）；多 Agent 协作要么太简单要么太重（6 种 orchestration 策略 + 共享记忆是直接回应）。AgentOS 想用一套统一 runtime 同时覆盖这三个痛点，而不是让用户拼 LangChain + LangGraph + LlamaIndex + Mastra。

快速安装

⚠️ README 未直接给出 @framers/agentos 的 latest 版本号，建议在安装前用 npm view @framers/agentos version 现场核实，避免被锁在旧版。

Node.js 20+：

mkdir agentos-quickstart && cd agentos-quickstart
npm init -y
npm install @framers/agentos
# 至少配一个 provider 的 key
export ANTHROPIC_API_KEY=sk-ant-xxx
# 或
export OPENAI_API_KEY=sk-xxx

主包是 Apache-2.0，@framers/agentos-bench 是 MIT。

核心用法

1) 单 Agent + 记忆

import { agent } from '@framers/agentos';

const tutor = agent({
  provider: 'anthropic', // 默认解析到当前 provider 默认模型，可用 model: 'claude-opus-4-8' 覆盖
  instructions: '你是一位耐心的计算机科学导师。',
  personality: { openness: 0.9, conscientiousness: 0.95 },
  memory: { types: ['episodic', 'semantic'], working: { enabled: true } },
});

const session = tutor.session('student-1');
await session.send('用类比讲一下递归。');
await session.send('能再展开讲一下吗？'); // 自动带入上文

⚠️ README 中 claude-sonnet-4-6 / claude-opus-4-8 等模型 ID 来自写作时点 Anthropic 控制台；Anthropic 模型迭代频繁，使用前请到控制台核对当前 production 模型 ID，如已下线请改用最新可用 ID。

2) Session 状态管理

Session 不开 memory 也存在，作为对话历史容器：

const stateless = agent({ model, memory: false, history: false }).session('job-1');
const bounded  = agent({ model, history: { maxTokens: 60_000 } }).session('job-2');
bounded.reseed([{ role: 'user', content: '压缩后的摘要' }]); // 替换历史

默认历史上限约 120K tokens，可在 history.maxTokens 调小。

3) Multi-Agent Team

import { agency } from '@framers/agentos';

const team = agency({
  strategy: 'graph', // sequential | parallel | debate | review-loop | hierarchical | graph
  agents: {
    researcher: { provider: 'anthropic', instructions: '搜集事实。' },
    writer:     { provider: 'openai',    instructions: '清晰总结。', dependsOn: ['researcher'] },
    reviewer:   { provider: 'gemini',    instructions: '校对准确性。', dependsOn: ['writer'] },
  },
});

const result = await team.generate('对比 TCP 与 UDP 在游戏网络中的取舍。');

hierarchical + emergent: { enabled: true } 时，管理者会运行时"锻造"子 Agent。

4) Soul 文件 + 长期记忆

把身份 / 声音 / HEXACO 分数放进 SOUL.md，把 memory/ 当 markdown wiki 维护：

import { souledAgent } from '@framers/agentos';
const aria = await souledAgent({
  provider: 'anthropic',
  soul: '~/.agentos/agents/aria',
});

memory/ 下的 index.md + entities/ + concepts/ + log/ 是 source of truth，向量/图索引会自动重建。

5) Provider fallback

显式 opt-in：

const a = agent({
  provider: 'anthropic',
  fallbackProviders: ['openai', 'groq'],
});

默认行为是"never silently re-route"，避免 quota 打满时悄悄换模型导致成本不可控。

典型适用场景

  • 长程陪伴 / 教学 Agent：LongMemEval-S 85.6% 的数字对应"100+ 轮后还记得小细节"，适合家教、心理陪伴、知识工作助理。
  • 运行时工具不足的开放任务：传统框架要开发者提前塞好全套 tool；AgentOS 的锻造路径适合"任务一来才发现缺什么工具"的探索型 Agent。
  • 多模型流水线：要把 Anthropic 强推理 + OpenAI 强写作 + Gemini 强审校串成 graph 工作流时，AgentOS 的 agency() 比裸调三家 SDK 干净。
  • Markdown-first 长期记忆：不愿意把记忆锁死在向量数据库的团队，可以把 memory/ 当 wiki 维护，人工可审计。

坑与注意

  1. ⚠️ 基准自报 vs 第三方复测：LongMemEval 的 85.6% / 70.2% 数字是项目方在自家 harness（agentos-bench，MIT）跑出的，对比对象（如 Mastra OM 84.23%）也是同一团队跑的；引入前最好自己用 agentos-bench 在目标预算下复测一次。
  2. ⚠️ node:vm 沙箱不等于真安全：锻造工具虽然禁了 eval / require / process 且有 5s wall clock 上限，但攻击面随 prompt 注入演化；对外暴露工具前必须叠加外层 guardrail pack（PII / 内容策略等）。
  3. ⚠️ HEXACO 不是 prompt 拼接：它是 kernel 级 trait，调的是检索权重与决策路径，不是 system prompt；引入后会让同一个 prompt 在不同 personality 下产生可观察到的差异行为——务必在 staging 跑回归。
  4. ⚠️ 6 种策略 ≠ 6 种配置：graph / hierarchical 的 emergent 模式会让运行时动态生成子 Agent，token 成本与延迟会比 sequential 高一档，预算敏感场景先用 sequential / parallel。
  5. ⚠️ CLI 工具是 preview：wunderland（CLI + daemon over AgentOS registries）当前标注 preview，生产环境先不要依赖。
  6. ⚠️ npm 供应链高危期：2026 上半年已发生 Mini Shai-Hulud 蠕虫等供应链事件，安装时建议固定版本 + npm install --ignore-scripts + 跑 socket.dev / aikido 扫描。

与同类对比

维度 AgentOS LangChain/LangGraph Vercel AI SDK CrewAI / Mastra
长记忆 8 机制 + 自报 85.6% S / 70.2% M 第三方 store 拼装 无内置 第三方
运行时造工具 是（LLM judge + node:vm） 否 否 否
多 Agent 编排 6 策略 + emergent Graph / LCEL 无 Crew / Mastra OM
HEAXCO 人格 是（kernel 级） 否 否 否
Provider 覆盖 11（含本地 CLI） 极广 极广 中
学习曲线 中-高（API 较多） 中 低 中

⚠️ 表格为 README 与各项目公开资料整理，未做端到端基准对比。

一句话推荐结论

如果你要构建一个"长时间陪伴 + 边做边造工具 + 多模型协作"的 TypeScript Agent，AgentOS 的认知记忆与锻造工具是当前开源里少见的差异化组合，建议先用 agent({ memory: ... }).session() 跑通单 Agent 主流程，再按需上 agency() 与 Soul 文件；预算敏感项目先复测 LongMemEval 数字再下生产决策。