Retrieval: a synchronous retrieval lifecycle with quota
Keep normalization, validation, deduplication, authorization, reading, and follow-up effects on one deterministic call path.
run(query, context) returns a RetrievalReceipt: the original query, the dedup key, the success sequence, the start time, rawResult, result with request-scoped sourceId values, and extensions. state(context) provides this request's queryCount, seen, and sources; limit(context) is the successful query quota.
The order is prepare → assertInput → dedup/quota → authorize → reserve the seen key → execute → assertResult → count successes and sources → effects. A failed attempt has already occupied its seen key and is not retried automatically because it failed. effects run in order, and a failure does not pretend to roll back earlier side effects. All ports are synchronous; asynchronous retrieval can be handled by the App's own ordinary Workflow node. The default key comes from retrievalQueryKey, and the default source ID is a combination of the retrieval ID, the success sequence, and the source ID, which is only a request-scoped reference.
Progressive examples for the same business case
Configure one read for the same product material
Beginner · Node.js
import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
id: 'manual-search', description: '读取已确认的本地演示资料',
assertInput(query: string) { if (!query.trim()) throw new Error('查询为空'); },
state: () => state, limit: () => 2,
execute: (query: string) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const documents = [{ sourceId: 'manual', text: 'Agent Core 使用指南' }];
const retrieval = Retrieval.defineRetrieval({
id: 'manual-search', description: '读取已确认的本地演示资料',
assertInput(query) { if (!query.trim())
throw new Error('查询为空'); },
state: () => state, limit: () => 2,
execute: (query) => ({ sources: documents.filter(item => item.text.includes(query)) }),
});
console.log(retrieval.run('Agent', { app: {}, signal: new AbortController().signal }).result);Add normalization, authorization, and receipt effects to the same run
Configuration · Node.js
import { Retrieval } from '@jangts/agent-core/kits/retrieval';
type Source = { sourceId: string; text: string };
const state = { queryCount: 0, seen: new Set<string>(), sources: [] as Source[] };
const retrieval = Retrieval.defineRetrieval<string, Source, { sources: Source[] }, { canRead: boolean }>({
id: 'manual-search', description: '按当前服务端权限读取资料',
prepare: query => query.trim(),
assertInput(query) { if (!query) throw new Error('查询为空'); },
state: () => state, limit: () => 2,
authorize(_query, { app }) { if (!app.canRead) throw new Error('没有资料读取权限'); },
execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);import { Retrieval } from '@jangts/agent-core/kits/retrieval';
const state = { queryCount: 0, seen: new Set(), sources: [] };
const retrieval = Retrieval.defineRetrieval({
id: 'manual-search', description: '按当前服务端权限读取资料',
prepare: query => query.trim(),
assertInput(query) { if (!query)
throw new Error('查询为空'); },
state: () => state, limit: () => 2,
authorize(_query, { app }) { if (!app.canRead)
throw new Error('没有资料读取权限'); },
execute: query => ({ sources: [{ sourceId: 'manual', text: 'Agent Core 使用指南' }].filter(item => item.text.includes(query)) }),
effects: [{ id: 'source-count', description: '给真实回执附加来源数量', handle(receipt) { receipt.extensions.sourceCount = receipt.result.sources.length; } }],
});
const receipt = retrieval.run(' Agent ', { app: { canRead: true }, signal: new AbortController().signal });
console.log(receipt.sequence, receipt.extensions);