defineAgentCatalog

KIT · function · Runtime value

Compile a catalog projection over the App's live registries.

The actual registries determine availability and relationships. No parallel capability list exists: goalIds filters by tool support, modelCatalog narrows to the currently accepted task when restrictToTask is enabled, and scope tool ids are filtered to tools that exist.

Import

TypeScript

import { defineAgentCatalog } from '@jangts/agent-core/kits/domains';

JavaScript

import { defineAgentCatalog } from '@jangts/agent-core/kits/domains';

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/kits/domains, @jangts/agent-core/kits.

Definition

Type parameters

Type parameter	Constraint	Default type
App	—	—
Id	string	—
Goal	CatalogGoal<Id>	—
Scope	CatalogScope	—

Call

defineAgentCatalog<App, Id extends string, Goal extends CatalogGoal<Id>, Scope extends CatalogScope>(ports: AgentCatalogPorts<App, Id, Goal, Scope>): Readonly<{ goalIds: (app: App) => Id[]; goalDelegates: (app?: App) => Map<Id, string[]>; goalCatalog: (app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]; scopeCatalog: (app: App) => (Scope & { toolIds: string[]; })[]; modelCatalog(app: App): { availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][]; availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]; availableScopes: (Scope & { toolIds: string[]; })[]; availableTools: DescribedTool[]; }; }>

Compile a catalog projection over the App's live registries.

The actual registries determine availability and relationships. No parallel capability list exists: goalIds filters by tool support, modelCatalog narrows to the currently accepted task when restrictToTask is enabled, and scope tool ids are filtered to tools that exist.

Type parameter	Constraint	Default type
App	—	—
Id	string	—
Goal	CatalogGoal<Id>	—
Scope	CatalogScope	—

Parameter	Type	Passing	Description
ports	AgentCatalogPorts<App, Id, Goal, Scope>	Required	—

Fields of ports

Field	Type	Required	Description
goalIds	(app: App) => readonly Id[]	Required	All registered Tool ids, before availability filtering.
goals	(ids?: readonly Id[] | undefined) => readonly Goal[]	Required	Registered domain Tools, optionally narrowed to ids.
scopes	(ids?: readonly Id[] | undefined) => readonly Scope[]	Required	Registered scopes for the given Tool ids (all scopes when omitted).
restrictToTask	boolean | undefined	Optional	Read-only. When not false, the catalog is narrowed to currentTask; defaults to restriction on.
currentTask	(app: App) => CatalogTask<Id> | undefined	Required	Task accepted for this request, if any.
tools	{ values(): Iterable<CatalogTool<App>>; has(id: string): boolean; supportsGoal(id: Id, app: App): boolean; describe(audience?: string, app?: App | undefined): readonly DescribedTool[]; }	Required	Read-only. See the type definition and usage context.

Returns: Readonly<{ goalIds: (app: App) => Id[]; goalDelegates: (app?: App) => Map<Id, string[]>; goalCatalog: (app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" \| "inputSchema" \| "active" \| "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string \| undefined; })[]; scopeCatalog: (app: App) => (Scope & { toolIds: string[]; })[]; modelCatalog(app: App): { availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][]; availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" \| "inputSchema" \| "active" \| "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string \| undefined; })[]; availableScopes: (Scope & { toolIds: string[]; })[]; availableTools: DescribedTool[]; }; }>.

Return value structure

Field	Type	Required	Description
goalIds	(app: App) => Id[]	Required	See the type definition and usage context.
goalDelegates	(app?: App) => Map<Id, string[]>	Required	See the type definition and usage context.
goalCatalog	(app: App) => (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]	Required	See the type definition and usage context.
scopeCatalog	(app: App) => (Scope & { toolIds: string[]; })[]	Required	See the type definition and usage context.
modelCatalog	(app: App) => { availableGoalIds: (Goal & Partial<ModelTool<unknown, unknown, App>>)["id"][]; availableGoals: (Omit<Goal & Partial<ModelTool<unknown, unknown, App>>, "resolve" | "inputSchema" | "active" | "asIntent"> & { delegates: string[]; scopeIds: string[]; toolIds: string[]; description?: string | undefined; })[]; availableScopes: (Scope & { toolIds: string[]; })[]; availableTools: DescribedTool[]; }	Required	See the type definition and usage context.

Examples

• Agent Catalog: generate the tool menu from real registrations: Tool, scope, and host tool menus are projected from the real catalogs instead of maintaining a separate tool list for prompts.

Project existing tools and scopes into a model menu

Beginner · Node.js

TypeScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'] }]);
const catalog = defineAgentCatalog({
  goalIds: () => tools.ids(), goals: ids => tools.describe(ids), scopes: ids => scopes.describe(ids), currentTask: () => undefined,
  tools: { values: () => [], has: () => false, supportsGoal: () => true, describe: () => [] },
});
console.log(catalog.modelCatalog(undefined));

JavaScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const tools = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'] }]);
const catalog = defineAgentCatalog({
    goalIds: () => tools.ids(), goals: ids => tools.describe(ids), scopes: ids => scopes.describe(ids), currentTask: () => undefined,
    tools: { values: () => [], has: () => false, supportsGoal: () => true, describe: () => [] },
});
console.log(catalog.modelCatalog(undefined));

Connect the same menu to actual tool declarations and the current task

Configuration · Node.js

The tools here are a structured projection port; a real application should connect directly to the corresponding methods of the real tool registry to avoid parallel maintenance.

TypeScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const goals = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'], toolIds: ['read-source'] }]);
const tools = [{ id: 'read-source', kind: 'read', description: '读取允许的说明资料', audience: 'model', effect: 'read', goalIds: ['explain'], lifecycle: { id: 'read' } }];
type App = { current?: { goalId: string; scopeId: string } };
const catalog = defineAgentCatalog<App, string, ReturnType<typeof goals.describe>[number], ReturnType<typeof scopes.describe>[number]>({
  goalIds: () => goals.ids(), goals: ids => goals.describe(ids), scopes: ids => scopes.describe(ids), currentTask: app => app.current,
  tools: { values: () => tools, has: id => tools.some(tool => tool.id === id), supportsGoal: () => true, describe: audience => tools.filter(tool => !audience || tool.audience === audience) },
});
console.log(catalog.modelCatalog({ current: { goalId: 'explain', scopeId: 'sdk' } }));

JavaScript

import { IntentRegistry, ScopeRegistry, defineAgentCatalog } from '@jangts/agent-core/kits/domains';
const goals = IntentRegistry.create([{ id: 'explain', description: '解释接口', delegates: ['reply'], asIntent: true }]);
const scopes = ScopeRegistry.create([{ id: 'sdk', description: 'SDK 资料', category: 'knowledge', goalIds: ['explain'], toolIds: ['read-source'] }]);
const tools = [{ id: 'read-source', kind: 'read', description: '读取允许的说明资料', audience: 'model', effect: 'read', goalIds: ['explain'], lifecycle: { id: 'read' } }];
const catalog = defineAgentCatalog({
    goalIds: () => goals.ids(), goals: ids => goals.describe(ids), scopes: ids => scopes.describe(ids), currentTask: app => app.current,
    tools: { values: () => tools, has: id => tools.some(tool => tool.id === id), supportsGoal: () => true, describe: audience => tools.filter(tool => !audience || tool.audience === audience) },
});
console.log(catalog.modelCatalog({ current: { goalId: 'explain', scopeId: 'sdk' } }));

Related policy source

• Generate a task-scoped menu from real catalogs

Related definitions

• AgentCatalogPorts
• CatalogGoal
• CatalogScope