活动跟进智能体

本页说明活动跟进智能体如何在用户委托下读取参会名单、互动记录和 CRM 备注，结合公开公司资料生成分组跟进草稿，并把草稿以草稿记录写回 CRM 等待销售确认。读完本页，你能理解这个场景需要哪些权限边界、为什么 CRM 是联系人信息的权威来源、以及 GUMem 为什么只装销售确认过的措辞偏好。

适用场景

Marketing 和销售团队需要在 webinar、展会或线下活动结束后快速整理参会者，并生成个性化跟进内容。参会名单散落在活动平台和 CRM 里，逐个查公司背景再写跟进邮件往往要拖到活动热度消退之后；而把整个 CRM 的读写权限交给脚本，风险远超这项工作本身的需要。

典型触发时机：

webinar 结束后 24 小时内，需要按参会互动情况分组发出第一轮跟进。
展会收集到一批名片和扫码记录，需要补齐公司上下文再交给销售。
季度活动复盘时，需要核对哪些参会者已有 CRM 记录、哪些是新联系人。

工程挑战

时效窗口：活动热度在 24–48 小时内衰减，人工逐个查公司背景赶不上这个窗口；但为了快而跳过事实核验，个性化内容就会出错并伤害客户关系。
个性化的事实边界：草稿里"贵司刚完成 B 轮"这类话必须有公开来源支撑；没有来源的推测一旦发出，比模板邮件更糟。
CRM 数据主权：分组、历史活动和联系人事实的唯一真相在 CRM。把这些复制进第二套存储会立刻产生漂移——Agent 的产出必须以草稿记录写回 CRM，由销售确认后才转正式数据。

模块组合

模块	角色	说明
GenAuth	核心	活动平台与 CRM 的授权读取：交互式委托、只读名单与备注、短时凭证、可撤销，不授予发送或改写正式字段的能力。
Web Agent	核心	登录活动平台或 CRM 读取名单与互动（Profiles 复用登录态），WebSearch 补公开公司资料，逐条保留来源。
GUMem	可选	仅保存销售确认过的长期措辞偏好（例如"跟进邮件避免感叹号"）。分组、历史活动和联系人事实以 CRM 为事实来源，不在 Memory 建第二份真相。

活动跟进智能体：场景架构

权限与委托边界

Agent 本身不持有任何固有权限。每次跟进任务的实际权限是三个集合的交集：用户真实权限 ∩ 显式委托范围 ∩ 企业批准边界。落到这个场景：

委托范围只覆盖"读取当前活动的参会名单、互动记录和相关 CRM 备注"，不包含发送邮件、改写 CRM 正式阶段或修改联系人字段。
活动平台与 CRM 登录属于高风险操作，必须走 mode: 'interactive'：用户在 Qoni Console 确认授权，凭证在服务端回调中兑换。
参会者个人信息只使用公开可见部分；委托范围不覆盖名单之外的客户隐私记录。
越权尝试（例如读取其他活动的名单或改写正式 CRM 记录）会被拒绝并留痕——审计链覆盖全部尝试。

注意：本样例申请 doAnything 产品权限。平台域名、活动范围等业务边界需要由应用和下游服务配置、校验；产品 scope 和 prompt 中的规则不提供这些细粒度限制。本样例未展示该配置。授权语义见 Delegate Token 与缩权。

工作流程

活动跟进智能体：工作流程

用户选择活动和跟进目标（例如首轮感谢、销售线索移交）。
应用发起交互式委托；用户在 Qoni Console 确认授权，服务端回调兑换凭证。
应用从规则库读取当前版本的跟进手册（分组标准、品牌语气、跟进规则），注入任务描述。
Web Agent 登录活动平台与 CRM，读取参会名单、互动记录和相关备注——CRM 是这些信息的权威来源。
检查点：登录墙、验证码或风控页出现时，Web Agent 应升级给人处理，而不是静默绕过。
Web Agent 通过 WebSearch 查询参会者所在公司的公开资料，只采集公开可见部分并保留来源 URL。
Agent 按互动程度分组，为每组生成跟进草稿，每条公司事实附来源。
应用侧校验草稿（无来源事实剔除），把草稿以草稿记录写回 CRM，附来源清单和 audit id，等待销售确认。
检查点：草稿中的每条公司事实都应能回溯到公开来源；无来源支撑的个性化内容不应进入草稿。

示例代码

本页使用已发布到 npm 的 @qoniai/qoni 0.9.0；下载包附带同版本 SDK，由 npm ci 安装。默认提供虚构浏览器工作坊的分组名单和活动备注，再用 Firefox 产品页补充产品事实。公开网页由真实 SDK 读取，业务输入在 scenarios.ts 中标记为 public-demo。

本演示不读取或写入 GUMem；任务输入来自页面清单和明确提供的业务数据。DoAnything 直接打开所给页面，按场景任务读取并形成输出。接入自己的数据时，用 --input 指定 JSON 文件；需要用户同意时用 --interactive 发起委托，站点登录与交互处理见 Qoni SDK。

下载完整可运行样例，或在文档仓库中执行：

bash

cd examples/qoni
npm ci
npm run case -- event-follow-up-agent
# 使用自己的输入
npm run case -- event-follow-up-agent --input /path/to/input.json

运行前设置服务端 QONI_ACCESS_KEY、QONI_SECRET_KEY。QONI_USER_ID 可指定业务已识别的 GenAuth 用户；未指定时，本地演示从绑定用户池取用户。涉及演示 Memory 写入时，程序创建独立用户以避免修改业务用户的偏好。

本场景的真实执行入口：

import { cliOptions } from '../runtime.js'
import { inputFile, runScenario } from '../run-case.js'

// 按活动分组和已提供的记录起草后续跟进内容。
const report = await runScenario('event-follow-up-agent', cliOptions(), inputFile())
// report.items：分组、演示参会者 ID、草稿和产品事实，交活动负责人审核。
// 校验字段：segment, attendeeIds, draft, facts.
console.log(JSON.stringify(report, null, 2))

入口按场景 ID 读取下面这段定义，代码直接引用实际执行的 scenarios.ts，注释按页面语言显示：任务描述、输出字段、来源字段、Web Search 查询（如有）、是否使用 Memory，以及演示输入。执行链会在任务描述后追加输入数据、搜索来源、召回的 Memory 和通用安全约束，拼成最终的任务描述，完整拼装逻辑见下方执行链。

// 按活动分组和已提供的记录起草后续跟进内容。
browser('event-follow-up-agent',
  'Use the synthetic event and attendee segments with cited public product facts to draft follow-up messages. Return a JSON array [{segment,attendeeIds,draft,facts}] with one item per segment, even when only one segment is supplied. Copy segment names and attendeeIds verbatim from the input; each fact contains claim and sourceUrl. Do not send messages, contact attendees or modify CRM.',
  ['segment','attendeeIds','draft','facts'], undefined, sample([firefox], { eventId:'demo-browser-workshop', segments:[{name:'browser-evaluators',attendeeIds:['demo-attendee-1']}], notes:'Attendees asked how to start using Firefox.' })),

这里的 runScenario()、browser()、research() 和 sample() 是样例包的应用函数。实际 SDK 调用都在下面的执行链中：委托与权限查询 → 所需的 Memory/搜索 → 网页任务或监控 → 校验与保存。fields、sourceField 规定本场景如何校验业务输出；它们由应用使用。辅助函数的完整实现在样例包的 runtime.ts 中。

查看实际 SDK 执行链

// 场景构造器：browser() 只调用 DoAnything；research() 先 Web Search 再 DoAnything；sample() 标记 public-demo 演示输入。
const firefox = 'https://www.mozilla.org/en-US/firefox/new/'
const manifesto = 'https://www.mozilla.org/en-US/about/manifesto/'
const privacy = 'https://www.mozilla.org/en-US/privacy/firefox/'
const support = 'https://support.mozilla.org/en-US/kb/get-started-firefox-overview-main-features'
// 演示文案规则会加入 prompt；它们不替代服务端权限或业务规则校验。
const policy = {
  version: 'demo-2026-09',
  approvedClaims: ['Describe only features supported by the cited page.'],
  forbiddenClaims: ['guaranteed security', '100% private', 'unverified pricing or performance'],
  voice: 'concise and warm',
}
const sample = (pages: string[], business: JsonObject = {}): JsonObject => ({
  dataset: 'public-demo', pages, policy, business,
  notice: 'Business records are synthetic demonstration inputs. Referenced websites and SDK execution are real.',
})
// fields 是必填输出字段；sourceField 指定需要校验 URL 格式的字段，memory 控制是否调用 GUMem。
const browser = (id: string, task: string, fields: string[], sourceField: string | undefined, input: JsonObject, memory = false): Scenario => ({
  id, products: ['doAnything'], task, fields, sourceField, input, memory,
})
const research = (id: string, task: string, fields: string[], sourceField: string, queries: string[], input: JsonObject, memory = false): Scenario => ({
  id, products: ['webSearch', 'doAnything'], task, fields, sourceField, queries, input, memory,
})

import { QoniScopes, type JsonObject, type RunResult } from '@qoniai/qoni'
import { readFileSync } from 'node:fs'
import { getScenario, type Scenario } from './scenarios.js'
import { appendTrace, checkInputCoverage, cleanupDemoUser, createContext, delegate, handleInteraction, inputEntryCount, isolateDemoUser, object, readWithRetry, renderScreenshot,
  save, saveArtifacts, searchHits, settled, settleRun, validateItems, withCleanup, type Context, type Options } from './runtime.js'

export async function runScenario(id: string, options: Options = {}, input?: JsonObject) {
  // 按场景 ID 读取真实任务定义；--input 只替换业务输入。
  const scenario = getScenario(id)
  const data = input ?? scenario.input
  if (scenario.memory && data.dataset !== 'public-demo' && options.mode !== 'interactive' && !options.userId && !process.env.QONI_USER_ID) {
    throw new Error('Business Memory writes require the current QONI_USER_ID; do not select an arbitrary bound user')
  }
  const context = await createContext(id, { ...options,
    skipUserResolution: scenario.memory && data.dataset === 'public-demo' })
  return withCleanup(context, async register => {
    register('isolated demonstration user', () => cleanupDemoUser(context))
    // 演示偏好写入隔离用户；业务 Memory 必须属于明确识别的当前用户。
    if (scenario.memory && data.dataset === 'public-demo') await isolateDemoUser(context)
    return await executeScenario(context, scenario, data)
  })
}

export async function executeScenario(context: Context, scenario: Scenario, input: JsonObject) {
  const pages = input.pages
  if (!Array.isArray(pages) || !pages.length || pages.some(page => typeof page !== 'string' || !/^https:\/\//.test(page))) {
    throw new Error('Input pages must be an array of HTTPS URLs')
  }
  if (input.requiresLogin === true && context.mode !== 'interactive') {
    throw new Error('Targets that require sign-in need --interactive and user-controlled login')
  }
  const memoryScopes = scenario.memory
    ? [QoniScopes.GUMEM_MEMORY_READ, QoniScopes.GUMEM_MEMORY_WRITE, QoniScopes.GUMEM_MESSAGE_WRITE] : []
  // delegate() 是应用函数，内部调用 delegateToken / completeDelegateToken。
  const grant = await delegate(context, scenario.id, scenario.products, memoryScopes)
  // 查询实际授权范围；readWithRetry() 只对可重试的读取错误有限重试。
  const { data: tokenInfo } = await readWithRetry(context, 'delegation introspection',
    () => context.qoni.genauth.introspectDelegationToken({ token: grant.token }))
  const info = object(tokenInfo)
  if (info.active !== true) throw new Error('The delegation token is not active')
  const audit = { grantId: grant.grantId, auditId: grant.auditId, scopes: info.scope }
  let memory: unknown
  if (scenario.memory) {
    // Session 将本次对话关联到当前用户，sessionId 由应用生成。
    const sessionId = `${scenario.id}-${Date.now()}`
    await context.qoni.gumem.createSession({
      token: grant.token, userId: context.userId, sessionId, title: scenario.id,
    })
    const preferences = object(input.business ?? {}).confirmedPreferences
    if (Array.isArray(preferences) && preferences.length) {
      // 只写入业务已经确认的偏好；sync: true 请求同步处理这次写入。
      await context.qoni.gumem.addMessages({ token: grant.token, userId: context.userId, sessionId, sync: true,
        messages: [{ role: 'user', content: `Confirmed demonstration preferences: ${preferences.join('; ')}` }] })
    }
    // 召回与任务有关的偏好，作为后续 prompt 的上下文。
    memory = (await readWithRetry(context, 'GUMem recall', () => context.qoni.gumem.recall({ token: grant.token, sessionId,
      query: 'Confirmed preferences relevant to this task', details: true }))).data
    save(context, 'memory.json', { sessionId, context: memory })
    if (Array.isArray(preferences) && preferences.length && !preferences.every(value => JSON.stringify(memory).includes(String(value)))) {
      throw new Error('Recall did not include the confirmed preferences just written by this demo')
    }
  }

  if (scenario.products.includes('track')) return runMonitor(context, scenario, input, grant.token, audit)

  let hits: ReturnType<typeof searchHits> = []
  if (scenario.queries) {
    // Web Search 返回真实 results[]；搜索来源将提供给 DoAnything 阅读。
    const search = await context.qoni.webSearch.run({ token: grant.token, prompt: scenario.queries, maxResultsPerQuery: 3 })
    save(context, 'search-ref.json', { runId: search.id, audit })
    await withCleanup(context, async register => {
      register('Web Search run', () => search.cancel('Documentation demonstration cleanup'))
      const result = await settleRun(context, search)
      save(context, 'search-result.json', result)
      settled(result)
      hits = searchHits(result.output)
    })
  }

  // 逐项对应输入的场景按输入项数要求条数，其余场景最多两项。
  const requiredItems = inputEntryCount(scenario.id, input)
  // 拼装场景任务、业务输入、搜索来源和 Memory；这些都是应用约定的上下文。
  const prompt = [scenario.task, `Task inputs: ${JSON.stringify(input)}`,
    `Search sources: ${JSON.stringify(hits)}`, `Confirmed memory: ${JSON.stringify(memory ?? null)}`,
    `Actual collection time: ${new Date().toISOString()}`,
    requiredItems === undefined
      ? 'Inspect the supplied sources. Return at most two items in the requested JSON array, without prose or Markdown.'
      : `Inspect the supplied sources. Return exactly ${requiredItems} item${requiredItems === 1 ? '' : 's'} in the requested JSON array, one per input entry, without prose or Markdown.`,
    'Keep synthetic demonstration data identified as synthetic. Do not send messages, publish, pay, edit accounts or submit forms.',
    input.requiresLogin === true ? 'Request user sign-in through an interaction when required; never enter credentials yourself.' : 'Public demonstration sources only; do not sign in.',
  ].join('\n\n')
  // 使用同一委托启动 Agent；capture 接收服务端交付的截图，不保证每步都有图。
  const run = await context.qoni.doAnything.run({ token: grant.token, prompt, capture: { screenshots: true } })
  save(context, 'run-ref.json', { runId: run.id, session: run.sessionRef, audit })
  let result: RunResult
  const trace = (event: { type: string; data: unknown }) => {
    context.eventCounts[event.type] = (context.eventCounts[event.type] ?? 0) + 1
    if (['progress','message','done'].includes(event.type)) appendTrace(context, event)
    if (event.type === 'browserLiveUrlChanged') {
      const liveUrl = object(event.data).liveUrl
      if (typeof liveUrl === 'string') context.browserUrl = liveUrl
    }
  }
  return withCleanup(context, async register => {
    register('DoAnything run', () => run.cancel('Documentation demonstration cleanup'))
    if (context.delivery === 'events') {
      // --events 实时读取事件；普通交互对象先转换为 SDK 句柄再交给用户处理。
      for await (const event of run.events({ signal: AbortSignal.any([context.abort.signal, AbortSignal.timeout(context.timeoutMs)]) })) {
        trace(event)
        if (event.type === 'screenshot') renderScreenshot(context, event.image)
        if (event.type === 'interaction') await handleInteraction(context, run.interactionHandle(event.data))
      }
      result = await settleRun(context, run)
    } else {
      // 回调模式在 wait 内接收同一次任务的事件；这里的辅助函数会保存图像和询问用户。
      result = await settleRun(context, run, { onEvent: trace,
        onScreenshot: (image, index) => renderScreenshot(context, image, index),
        onInteraction: interaction => handleInteraction(context, interaction) })
    }
    save(context, 'result.json', result)
    settled(result)
    await saveArtifacts(context, result)
    if (scenario.id === 'landing-page-audit-agent' && context.screenshots === 0) throw new Error('The landing-page audit did not deliver the requested screenshot')
    // 应用校验必填字段和来源 URL 格式；事实准确性仍需业务复核。
    const items = validateItems(result.output, scenario.fields, scenario.sourceField)
    // 要求逐项对应输入的场景，再核对每个输入项都有对应输出。
    checkInputCoverage(scenario.id, items, input)
    const report = { scenario: scenario.id, dataset: input.dataset, passed: true, runId: run.id,
      status: result.status, items, audit, screenshots: context.screenshots, interactions: context.interactions,
      events: context.eventCounts, artifactIds: result.artifacts.map(artifact => artifact.id) }
    save(context, 'report.json', report)
    return report
  })
}

async function runMonitor(context: Context, scenario: Scenario, input: JsonObject, token: string, audit: JsonObject) {
  // Track 单独创建 monitor：声明目标、抽取字段并请求每小时调度。
  const monitor = await context.qoni.track.create({ token, prompt: scenario.task,
    targetUrls: input.pages, extractionSchema: { heading: 'string', source_url: 'string' },
    tickInstructions: `Open the target URLs and read the actual visible heading. Return a JSON object with heading and source_url. ${scenario.task}`,
    triggerDsl: { on: 'change' }, schedule: { kind: 'interval', intervalSeconds: 3600 } })
  save(context, 'monitor-ref.json', { id: monitor.id, audit })
  return withCleanup(context, async register => {
    register('Track monitor', () => monitor.delete())
    const definition = await monitor.get()
    save(context, 'monitor-definition.json', definition)
    if (object(definition.schedule).intervalSeconds !== 3600) throw new Error('Track did not persist the requested schedule interval')
    // 立即运行一次，再读取该 runId 的实际抽取；completed 本身不足以证明取数成功。
    const tick = await monitor.runNow()
    save(context, 'tick.json', tick)
    if (tick.state !== 'completed') throw new Error(`Track execution failed: ${tick.state} / ${tick.error ?? ''}`)
    const runId = tick.runId
    if (typeof runId !== 'string') throw new Error('Track tick did not return a runId')
    const detail = await monitor.run(runId)
    save(context, 'tick-detail.json', detail)
    if (detail.state !== 'completed' || !detail.extracted || !Object.keys(object(detail.extracted)).length) {
      throw new Error('Track did not extract page data')
    }
    const extracted = object(detail.extracted)
    if (typeof extracted.heading !== 'string' || !extracted.heading.trim() ||
      typeof extracted.source_url !== 'string' || !/^https:\/\//.test(extracted.source_url)) {
      throw new Error('Track extraction is missing a heading or source URL')
    }
    const normalizeUrl = (value: string) => { const url = new URL(value); url.hash = ''; return url.href.replace(/\/$/, '') }
    if (!(input.pages as string[]).some(url => normalizeUrl(url) === normalizeUrl(String(extracted.source_url)))) {
      throw new Error('The Track source URL is not a configured target')
    }
    // 检查暂停/恢复是否保存；withCleanup() 在退出时调用 monitor.delete()。
    await monitor.pause()
    if ((await monitor.get()).status !== 'paused') throw new Error('Track did not persist the paused state')
    await monitor.resume()
    if ((await monitor.get()).status !== 'active') throw new Error('Track did not persist the active state')
    const report = { scenario: scenario.id, dataset: input.dataset, passed: true, monitorId: monitor.id,
      runId, state: detail.state, outcome: detail.outcome, extracted: detail.extracted, audit }
    save(context, 'report.json', report)
    return report
  })
}

export function inputFile(): JsonObject | undefined {
  const index = process.argv.indexOf('--input')
  return index >= 0 ? object(JSON.parse(readFileSync(process.argv[index + 1], 'utf8'))) : undefined
}

结果写入 output/event-follow-up-agent/report.json。report.items 包含分组、演示参会者 ID、草稿和产品事实，交活动负责人审核，字段为 segment, attendeeIds, draft, facts；audit 保存委托 ID、审计 ID 和实际授权范围，http.json 记录脱敏请求状态。应用解析 DoAnything 输出，并检查必填字段。内容判断仍需业务人员结合原始来源复核。

数据与记忆边界

这个场景涉及四类数据，只有最后一类可选地属于 GUMem：

版本化规则：分组标准、品牌语气、跟进规则——放在跟进手册（playbook）里按版本管理，每批草稿引用手册版本号。
业务状态：分组结果、跟进草稿、公司事实与来源——以草稿记录写回 CRM；分组、历史活动和联系人事实以 CRM 为事实来源，不建第二份真相。
审计记录：交互式授权、每次读取与越权拒绝构成的行为链——由 GenAuth 维护。
用户 Memory（可选）：销售确认过的长期措辞偏好（例如"跟进邮件避免感叹号"）——这才是 GUMem 的位置；单次活动整理默认不召回也不写回。

失败处理

情况	推荐处理
活动平台或 CRM 登录态失效	任务挂起，通知用户重新登录，从断点继续整理。
参会者公开资料查不到或来源不可靠	该联系人只保留名单内信息，不填充推测的公司背景。
委托范围外的 CRM 记录请求	直接拒绝并记录，事后可在审计链中查到未遂访问。
草稿中的事实缺少来源	应用侧校验剔除该事实，并在交付物中标注剔除数量。

生产注意点

不要自动发送邮件或改写 CRM 正式字段：草稿以草稿记录写回 CRM，由销售确认后才转正式数据，发送动作始终属于人的职责。参会者个人信息只使用公开可见部分，超出名单范围的个人数据不应进入草稿、CRM 草稿记录或 Memory。

下一步

阅读快速开始跑通 Agent 身份与委托的最短路径。
阅读授权与浏览器沙盒了解受控会话的安全边界。
继续查看竞争情报智能体了解相邻的研究场景。

活动跟进智能体 ​

适用场景 ​

工程挑战 ​

模块组合 ​

权限与委托边界 ​

工作流程 ​

示例代码 ​

数据与记忆边界 ​

失败处理 ​

生产注意点 ​

下一步 ​