Comp AI CRM Agent 运行时指令解析:会话目的隔离与"绝不虚构"的事实权威边界

原创2026-09-24 20:47:181,951 阅读
文章标签:人工智能AI AgentCRM企业应用后端前端工具调用

Comp AI CRM Agent 运行时指令解析:会话目的隔离与"绝不虚构"的事实权威边界

导读

本文围绕 Comp AI CRM(Agentic-first 开源 CRM)中 AI Agent 运行时的基础指令(apps/agent/agent/instructions.md)展开,逐条拆解这条指令背后的设计意图与工程实现:为什么 Agent 必须只服从当前会话的特定目的、为什么"绝不虚构 CRM 记录/集成/动作/外部副作用"是一条不可逾越的红线,以及"工具与持久化状态是权威"这句话在代码里是如何被落实的。读完本文,你将理解 Comp AI 的 Eve 运行时如何通过会话指令分发、证据评分、动作幂等与持久化审计来约束一个长期运行的(durable)AI Agent,使其在真实 CRM 环境中可被信任。

一、指令的定位:一份写给"长期运行 Agent"的宪法

apps/agent/agent/instructions.md 全文只有两段,却是整个 Agent 运行时的行为基石:

You are the durable Eve runtime behind Comp AI CRM. The session-specific
instructions identify the only purpose of the current session. Follow that
purpose exactly and do not borrow tools or behavior from another purpose.

Never invent a CRM record, connected integration, completed action, or external
side effect. Tools and persisted state are the authority for what exists and
what happened.

把它翻译成工程语言,可以得到三条约束:

  1. 身份约束:Agent 是"持久化运行的 Eve 运行时"(durable Eve runtime),不是一次性对话机器人,它的行为要对跨会话的状态负责;
  2. 目的约束:当前会话的目的由"会话特定指令"(session-specific instructions)唯一确定,Agent 不得借用其他目的的工具与行为;
  3. 事实约束:永远不得虚构 CRM 记录、已连接的集成、已完成的动作或外部副作用;工具返回结果与数据库中的持久化状态,才是判断"什么存在、发生了什么"的唯一权威。

这三条约束在 agent.ts 中得到了运行时层面的印证——Agent 的默认模型、会话 token 预算与超时都是在这个入口统一配置的:

export default defineAgent({
	model: defineDynamic({
		fallback: DEFAULT_AGENT_MODEL.id,
		events: { "session.started": () => selectedModel() },
	}),
	limits: {
		maxInputTokensPerSession: 500_000,
		maxOutputTokensPerSession: 50_000,
		sessionTimeoutMs: 30 * 24 * 60 * 60 * 1000, // 30 天
	},
});

其中 defineDynamic 会在每次会话开始时动态选择模型,limits 定义了单会话 50 万输入 token、5 万输出 token 的预算,以及 30 天的会话生命周期——这正是"durable"(可长期存活、可恢复)运行时的直接体现。

二、会话目的隔离:三种 purpose 如何被分发

"Session-specific instructions identify the only purpose"这句话,在代码中的对应物是 lib/session-purpose.ts 中的 purposeOf 函数:

export type SessionPurpose = "builder" | "team-agent" | "research";

export function purposeOf(ctx: PurposeContext): SessionPurpose {
	const purpose = attribute(ctx, "purpose");
	if (purpose === "builder" || purpose === "team-agent") return purpose;
	return "research";
}

会话目的通过会话属性(attributes)注入,取值只有三种:

Purpose 场景 关键约束(来自 instructions/task.ts)
builder 创建/修订 Agent 的对话 只允许调用 agent_builder 子代理一次,不得自行使用研究工具或修改 CRM 记录;agent_builder 失败时不得在同一轮重试
team-agent 已部署团队 Agent 的后台运行 只调用一次 agent_runner 并传入 run id,不得自己做研究;"绝不声称专家未记录的外部动作"
research(默认) 面向 CRM 记录的会话/任务 依据记录类型(contact/company/deal/无记录)生成对应的 preamble,配合研究工具完成查询与事实记录

目的分发发生在 session.started 事件中(instructions/task.ts),turn.started 时 builder 会话还会重新生成指令,确保目的指令在每一轮都生效。同时,工具层用 assertResearchPurpose 之类的守卫做二次校验——例如 tools/record_fact.ts 中的 assertResearchPurpose(ctx),非研究会话直接抛错。这就是"不借用其他目的的工具"的代码级实现:分发层管指令,工具层管权限,双层隔离。

三、会话上下文注入:Agent 从不凭空猜测记录

在"研究"目的下,sessionPreamble(lib/preamble.ts)会根据会话绑定的记录类型,从数据库读取真实数据并注入指令:

  • 联系人为焦点:读取姓名、邮箱、职位、所属公司、最近 5 个 deal、邮件/日历往来数量,并明确给出 contactId,指示"先用 read_crm_history 读这段记录";
  • 公司为焦点:读取行业、描述、最多 12 个联系人(含 id)与 8 个 deal,生成"Who we know there"清单;
  • deal 为焦点:读取阶段、金额、币种、预期关闭日期、参与者;
  • 无记录:明确告诉 Agent "No record was named, so nothing is in focus yet",并引导使用 search_crm、list_outstanding_work 自行查证,而不是向用户索要 id。

注意 preamble 中反复出现的措辞:"Never ask them for an id, a name or an address you can look up yourself"(永远不要向用户要你自己能查到的 id、姓名或地址)。这与基础指令一脉相承:Agent 的知识来源只能是工具调用和持久化状态,而不是用户的随口回答。研究指令(lib/research-instructions.ts)同样强调:"Never write a fact you have not read from a source. A confidently wrong fact is worse than a missing one."(绝不写你没有从来源读到的事实;一个有把握的错误事实比缺失更糟。)

四、"绝不虚构"的第一道闸门:证据评分与事实落库

基础指令的第二段是运行时最重要的安全声明。它的落地核心是 record_fact 工具与 lib/evidence.ts 中的证据评分机制。

4.1 证据种类与权重表

record_fact 要求 Agent 每记录一条事实,必须同时提交"证据种类 + 细节描述",证据种类定义在 lib/evidence.ts:

证据种类 权重 是否主证据 含义
profile.email-match 0.95 是 资料页本身展示了我们持有的邮箱,决定性
linkedin.employer-and-name 0.85 是 LinkedIn 雇主匹配且姓名与邮箱一致
crm.thread-reply 0.85 是 对方从该地址回复了我们同步的邮件线程
crm.signature-block 0.80 是 对方自己的邮件签名如此声明(职位最佳来源)
github.account-identity 0.80 是 GitHub 账号的 name(或 name+company)匹配
crm.meeting-attendance 0.70 是 对方接受了我们日历上的会议邀请
web.cited-claim 0.40 否 网页声明了该事实且带有 URL
handle.name-form 0.35 否 账号名是姓名的某种构造(弱)
search.cites-profile 0.35 否 按姓名+雇主搜索时该资料被引用
employer-only 0.20 否 仅雇主匹配、姓名不匹配(几乎无价值)
contradiction 0 — 两个来源相互矛盾(直接"按住"事实)

4.2 评分算法与事实分级

评分逻辑在 scoreEvidence(lib/evidence.ts):先对每条证据按 1 - weight 连乘得出组合分,再取 min(CEILING=0.99, 1-combined);只要存在 contradiction 证据,最终分数被钳制到 0.45 以下。分级门槛为:

export const BAND_FLOOR = { VERIFIED: 0.85, PROBABLE: 0.55, POSSIBLE: 0.3 };
  • VERIFIED(≥0.85 且含主证据):直接写入记录字段;
  • PROBABLE / POSSIBLE(≥0.3):作为"建议"存到字段下,等待真人审批;
  • 弱证据(<0.3)或无证据:不落库,lib/facts.ts 会返回 "Below the floor for keeping — not stored"。

这就是"工具与持久化状态是权威"的落地:Agent 无法自行"设置置信度"(skills/evidence.md 明确写着 "You never set a confidence. You report what you saw, and the ledger prices it."),它只报告所见,系统用算法定价。record_fact 的工具描述也直接呼应基础指令:"Never invent evidence you did not observe."(绝不虚构你没观察到的证据。)

4.3 矛盾证据的处理哲学

值得单独强调的是 contradiction 的处理:它"不是把分数降低一点,而是完全按住事实"(skills/evidence.md)。一个资料页说 A 雇主、邮件头说 B 雇主,不是"60% 为真",而是"未决",应该让销售代表看到这种未决状态,而不是由 Agent 加权出一个虚假的确定性。

五、"已完成动作"的权威:幂等执行与动作回放

基础指令要求 Agent 不得虚构"已完成动作"。这在 lib/run-runtime.ts 中有非常扎实的工程保障——每个外部动作(写活动、发 Slack 消息)都走"幂等键 + 请求哈希 + 动作认领"流程:

  1. 每次动作调用以 ${runId}:${callId} 作为幂等键(idempotencyKey),连同请求哈希一起查库(findRunAction);
  2. 若已存在且请求哈希一致且状态为 SUCCEEDED,直接返回既有结果并标记 replayed: true——动作绝不重复执行;
  3. 否则通过 claimRunAction 在事务内加锁并认领动作(lib/run-runtime.ts),对已超租约(ACTION_LEASE_MS)的 RUNNING 动作允许重新认领;
  4. 动作成功后把 externalId(如 Slack 的 channel:ts、CRM 活动 id)写回 agentAction 记录,作为"已发生"的持久化凭证。

Slack 消息投递还额外使用 client_msg_id 作为 Slack 侧的幂等键,并在发送前通过 holdRunActionClaim 再次确认运行仍存活(lib/run-runtime.ts);如果运行时已停止但 Slack 已接受消息,会调用 recordDeliveryOutsideClaim 记录"无法撤回"的真实状态。"外部副作用是否存在"由这些持久化动作记录说了算,而不是由 Agent 的记忆说了算——这正是运行时指令的工程化身。

六、收尾校验:声明了动作就休想"无事发生"地结束

基础指令的反面是:如果 Agent 的版本清单(manifest)声明了某个外部动作,那么运行结束时系统会强制校验。finishRun(lib/run-runtime.ts)在事务内依次执行:

  • noActionNeededRefusal:对声明了动作的 Agent,禁止以 "no action needed" 结束运行,错误信息明确要求:"Perform the declared action, or report why it failed.";
  • requiredActionFailure:遍历 manifest 声明的每个动作类型,若 agentAction 中没有 SUCCEEDED 记录,则运行以 FAILED 收场(错误码 ACTION_NOT_PERFORMED 或 NO_EXECUTOR),并落一条 run.failed 事件与审计事件(agentAuditEvent)。

这条闭环的意义在于:Agent 声称完成的事,必须有持久化动作记录佐证;否则运行失败,而不是假装成功。与 stageRunResult(lib/run-runtime.ts)配合,形成"先暂存结果、再终态校验、最后落审计"的完整生命周期。

七、能力声明:什么可用、什么不可用,都写进指令

指令中"不虚构已连接的集成"同样有对应机制:每个会话的 closing 部分会注入当前安装实际可用的能力清单(lib/capabilities.ts),包括:

能力 来源 未配置时的处理
网络研究(Perplexity) 环境变量 PERPLEXITY_API_KEY 视为不可用,不当作失败
公司品牌数据(Context.dev) Settings → General 中的 key 同上
LinkedIn 读取 Context.dev key 同上
图片存储 环境变量 BLOB_READ_WRITE_TOKEN 记录将没有图片

未配置的能力会以 "Not configured here, so do not plan around them" 明确列出,并指示 Agent "Note what you could not check rather than guessing at it"(记录你没查到的内容,而不是猜测)。unavailable 函数(lib/capabilities.ts)甚至直接生成了提示文本:"This install has no ... so that source is unavailable. This is not a failure and retrying will not help."——Agent 被训练/约束为:承认能力缺失,而不是假装集成存在。

八、延伸阅读路径

总结

apps/agent/agent/instructions.md 虽然只有两段话,却是 Comp AI CRM 整个 Agent 体系的宪法性文件:目的隔离由 session-purpose 分发与工具守卫双层落实;绝不虚构由证据评分、事实分级、矛盾按住机制三层把关;持久化状态是权威由幂等动作认领、Slack client_msg_id 重放防护、终态动作校验与审计事件兜底。任何在此仓库上二次开发 Agent 能力的人,都应当先把这两段话当作不可违反的系统约束来理解——它决定了 Comp AI 的 Agent 是一个"宁可留空、绝不编造"的可信助手。

登录后查看全文
crm