Agent Core API

本手册按模块说明当前 SDK。精确类型和全部重载见公开符号参考。

Core 定义运行接口和执行保证，Support 提供推荐实现与配置策略，Kit 提供 App 可选的业务能力。纯算法使用各自的输入输出合同。

第一次接触这些配置时，先读独立配置与关联配置：完整代码对照：从可运行的笔记工具开始，对照 Tool 模型接口、执行扩展、意图用途标记、上下文与节点的完整配置，检查独立和关联写法生成的模型声明及执行结果。

从这七条规律开始

1. 实体用 id，指向实体用 toolId、documentId 等；name 是显示名。
2. jsonSchema 总是只读 JSON Schema；inputSchema 总是 SchemaAdapter<T>，其中的 parse 负责真实解析。
3. is/can/has 返回布尔；assert/authorize 通过时返回 void、失败抛错；check 返回问题报告；parse 返回转换后的值。
4. define 编译静态声明，create/new 建立适配器或运行实例。请求状态、signal和预算在运行时绑定。
5. 输入在前、上下文在后。复杂调用用命名请求；get(id) 缺失返回 undefined，require(id) 缺失抛错。
6. invoke成功统一返回{ value, invocation }；输入短写只归一输入，文本和结构化值都放在value里，失败统一抛错。
7. observer 是不阻断业务的观察；sink 是需要等待的交付。两者不因都返回 Promise 而具有相同语义。

导入与阅读顺序

import { AgentCoreEngine, ModelRunner, Support } from '@jangts/agent-core';
import { defineKnowledgeCatalog } from '@jangts/agent-core/kits/knowledge';
import { defineAnswerFlow } from '@jangts/agent-core/kits/answering';
import type { SchemaAdapter, OperationContext, Issue } from '@jangts/agent-core';

Core 服务及共同合同从根入口，接入辅助从 Support，Kit 从各自独立入口使用具名函数或构造器。全量 /kits 与单项入口转出同一实现。

顺序	文档	学到什么
1	共同类型与规则	身份、schema、校验、错误、上下文、集合、所有权
	工作流入门	Agent 绑定、节点、路由和派生
2	Core	模型调用、能力、工具执行、工作流和事件
3	Support	schema、工具与能力清单、传输和上下文装配
	上下文处理	预算、水位、压缩与原文保护
4	知识、回答与展示	取证、检查、局部修正、程序绑定输出
5	其余 Kit	意图、交互、检索、规则、产物和持久任务
	复盘、分支和资料发布	有界子任务、元数据证据、持久版本与来源校验
6	连贯示例	用同一套合同声明工具、调用模型并执行真实操作

日志与Journal的统一事实源、调用链关联及关系表映射见请求、调用链与Journal。

单页速查

任务	首选接口	结果
一次模型调用	runner.invoke({ stageId, input, transport })	ModelResult：value为完整解析值，原始分片只进sink
执行工具	tools.invoke({ toolId, input })	ToolResult：value为已解析、授权、执行并检查的实际结果
编译工作流	defineWorkflow(definition)	不绑定请求的 Workflow
运行工作流	agent.run(state)	满足最终结果合同的值
声明工具	Support.defineTool(definition)	与模型schema同源的类型化定义
创建请求工具实例	catalog.bind({ app, execution })	生命周期仅限本次请求的 ToolRuntime
取得登记项	catalog.get(id) / catalog.require(id)	可缺失查询／必须存在查询
检查值	checker.check(value, context)	CheckResult，不是boolean或异常别名
读取资料	knowledge.read({ documentId, selection })	带版本、选择和身份的快照
恢复持久任务	task.run({ taskId, store }, context)	已确认结果的副本；不会自动重放写操作

同步算法继续同步。源schema、权限、预算、取消和最终提交检查不会因为采用这些辅助接口而放宽。App 自己的业务状态不升级为所有 Kit 的必需字段。

模拟模型

MockGPT Kit 说明 @jangts/agent-core/mock 及其 /node、/web 入口：规则与生成器、直接返回值、HTTP/SSE、工具提议、网页来源、错误、取消与预算。

• 装饰器与定义池

开发辅助接口不参与任务执行；工作流的静态拓扑与按 run 查询的执行链见工作流图与执行链。