defineContextAssembly
SUPPORT · function · Runtime value
Compile ordered context projections into a builder.
A projection is either a single fragment (with its own formatter) or a placement whose contribution handler expands to any number of fragments at request time.
Import
ts
import { defineContextAssembly } from '@jangts/agent-core/support';js
import { defineContextAssembly } from '@jangts/agent-core/support';Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/support, @jangts/agent-core/support/context.
Definition
Type parameters
| Type parameter | Constraint | Default type |
|---|---|---|
Input | — | — |
Id | string | string |
Placement | string | string |
Call
ts
defineContextAssembly<Input, Id extends string = string, Placement extends string = string>(definitions: readonly ContextProjection<Input, Id, Placement>[], options: ContextAssemblyOptions<Input, Id, Placement>): ContextBuilder<Input>Compile ordered context projections into a builder.
A projection is either a single fragment (with its own formatter) or a placement whose contribution handler expands to any number of fragments at request time.
| Type parameter | Constraint | Default type |
|---|---|---|
Input | — | — |
Id | string | string |
Placement | string | string |
| Parameter | Type | Passing | Description |
|---|---|---|---|
definitions | readonly ContextProjection<Input, Id, Placement>[] | Required | — |
options | ContextAssemblyOptions<Input, Id, Placement> | Required | — |
Fields of options
| Field | Type | Required | Description |
|---|---|---|---|
fragment | (id: Id, value: ContextFragment["value"]) => ContextFragment | Required | Read-only. Builds a fragment for a single-fragment projection. |
contributions | Readonly<Record<Placement, (input: Input) => readonly ContextFragment[]>> | undefined | Optional | Read-only. Contribution handlers keyed by placement; each expands to zero or more fragments. |
maxInputChars | number | ((input: Input) => number) | undefined | Optional | Read-only. Character budget, constant or derived from the request; at least one of these is required. |
transform | ((fragment: ContextFragment, input: Input) => ContextFragment) | undefined | Optional | Read-only. Applied to every produced fragment before assembly; must be synchronous. |
Returns: ContextBuilder<Input>.
Return value structure
| Field | Type | Required | Description |
|---|---|---|---|
fragments | (input: Input) => ContextFragment[] | Required | Produces the fragments for one input, after transforms. |
build | (request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">) => BuiltContext | Required | Assembles and validates the plan into messages with usage accounting. |
plan | (request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">) => ContextPlan | Required | Produces the unassembled plan without running the budget boundary. |
Examples
- Context assembly: configure stable metadata once: Support binds fragment metadata, formatting, and order in advance, and requests supply only the changing business input.
Configure once, then supply only question and history
Beginner · Node.js
ts
import { Support } from '@jangts/agent-core';
type Input = { question: string; history: readonly { role: string; content: string }[] };
const builder = Support.defineContextFragments<Input>([
{ id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
role: 'user', format: input => input.question },
{ id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const context = builder.build({ input: { question: '服务状态？', history: [] } });
console.log(context.messages);js
import { Support } from '@jangts/agent-core';
const builder = Support.defineContextFragments([
{ id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
role: 'user', format: input => input.question },
{ id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const context = builder.build({ input: { question: '服务状态？', history: [] } });
console.log(context.messages);The same builder produces a plan in advance
Configuration · Node.js
ts
import { Support } from '@jangts/agent-core';
type Input = { question: string; history: readonly { role: string; content: string }[] };
const builder = Support.defineContextFragments<Input>([
{ id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
role: 'user', format: input => input.question },
{ id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const input = { question: '服务状态？', history: [] };
const plan = builder.plan({ input });
const expanded = builder.fragments(input);
console.log(plan.maxInputChars, expanded.map(fragment => fragment.id));
const largerRequest = builder.build({ input, maxInputChars: 2000 });
console.log(largerRequest.maxInputChars);js
import { Support } from '@jangts/agent-core';
const builder = Support.defineContextFragments([
{ id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
role: 'user', format: input => input.question },
{ id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const input = { question: '服务状态？', history: [] };
const plan = builder.plan({ input });
const expanded = builder.fragments(input);
console.log(plan.maxInputChars, expanded.map(fragment => fragment.id));
const largerRequest = builder.build({ input, maxInputChars: 2000 });
console.log(largerRequest.maxInputChars);Reuse a metadata catalog and request contribution slots
Extension · Node.js
ts
import { Support } from '@jangts/agent-core';
import type { ContextFragment } from '@jangts/agent-core/types';
type Input = { question: string; evidence: string };
const builder = Support.defineContextAssembly<Input, 'question', 'evidence'>([
{ kind: 'fragment', id: 'question', format: input => input.question },
{ kind: 'contributions', placement: 'evidence' },
], {
maxInputChars: 2000,
fragment(id, value): ContextFragment { return { id, sourceId: 'request', trust: 'user', lifetime: 'turn', role: 'user', maxChars: 1000, value }; },
contributions: { evidence(input) { return [{ id: 'evidence', sourceId: 'service', trust: 'server', lifetime: 'turn', role: 'user', maxChars: 1000, value: input.evidence }]; } },
});
console.log(builder.build({ input: { question: '状态？', evidence: '最近检查：正常' } }).messages);js
import { Support } from '@jangts/agent-core';
const builder = Support.defineContextAssembly([
{ kind: 'fragment', id: 'question', format: input => input.question },
{ kind: 'contributions', placement: 'evidence' },
], {
maxInputChars: 2000,
fragment(id, value) { return { id, sourceId: 'request', trust: 'user', lifetime: 'turn', role: 'user', maxChars: 1000, value }; },
contributions: { evidence(input) { return [{ id: 'evidence', sourceId: 'service', trust: 'server', lifetime: 'turn', role: 'user', maxChars: 1000, value: input.evidence }]; } },
});
console.log(builder.build({ input: { question: '状态？', evidence: '最近检查：正常' } }).messages);