API Surface

Draft interface

下面的示例用于表达集成意图，不代表最终 SDK 或 HTTP 协议。

Identity APIs

Identity API 负责把用户身份、Agent Profile 和工具权限绑定到一个可审计的授权上下文中。

const { data } = await qoni.delegateToken({
  mode: 'interactive',
  agent: 'agent_researcher',
  scopes: ['webagent.web_search:manage', 'webagent.web_search:read'],
  redirectUri: 'http://localhost:3000/qoni/callback',
  state: 'req-001',
  user: { id: 'user_123' },
  expiresIn: 1800, // 秒
})

权威契约

Identity 的完整端点、字段与错误码见 GenAuth 的 API Reference 与 SDK Reference——那两页与代码逐项核对。

关键问题：

• 谁拥有 root authority。
• Agent 能代表用户做什么。
• 授权何时过期，如何撤销。
• 审计日志如何查询。

Memory APIs

Memory API 负责写入、检索、解释和擦除用户上下文。

const { data: context } = await qoni.gumem.recall({
  token,
  sessionId: 'daily-assistant',
  query: 'Find laptops for local LLM work'
})

关键问题：

• 记忆类型如何分层。
• 检索结果如何解释来源。
• 记忆冲突如何更新。
• 用户如何擦除特定记忆。

Web Data APIs

Web Data API 负责把开放网络转化为结构化输入，并在沙箱中执行浏览器动作。

const page = await qoni.web.textify({
  url: 'https://example.com/report',
  format: 'markdown'
})

const result = await qoni.web.search({
  query: 'agent memory benchmark',
  mode: 'research'
})

关键问题：

• 搜索结果如何排序、摘要和引用。
• 动态网页如何渲染和抽取。
• 沙箱执行如何隔离和追踪。
• 长任务如何监控变化。

推荐接入顺序

1. 接入 GenAuth，建立用户和智能体的授权边界。
2. 接入 GUMem，沉淀可解释的用户上下文。
3. 接入 Web Agent，让智能体连接真实网页数据。