AgentCatalogPorts

KIT · interface · Type contract

Ports the catalog reads from the App's registries.

Import

TypeScript

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

JavaScript

/** @typedef {import('@jangts/agent-core/kits/domains').AgentCatalogPorts} AgentCatalogPorts */

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

Definition

interface AgentCatalogPorts<App, Id, Intent, Scope>

Type parameters

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

Field structure

Field	Type	Required	Description
goalIds	(app: App) => readonly Id[]	Required	All registered Tool ids, before availability filtering.
goals	(ids?: readonly Id[]) => readonly Intent[]	Required	Registered domain Tools, optionally narrowed to ids.
scopes	(ids?: readonly Id[]) => 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): readonly DescribedTool[]; }	Required	Read-only. See the type definition and usage context.

Member index

Member	Purpose
goalIds	All registered Tool ids, before availability filtering.
goals	Registered domain Tools, optionally narrowed to ids.
scopes	Registered scopes for the given Tool ids (all scopes when omitted).
currentTask	Task accepted for this request, if any.

Member details

goalIds

All registered Tool ids, before availability filtering.

AgentCatalogPorts.goalIds(app: App): readonly Id[]

All registered Tool ids, before availability filtering.

Parameter	Type	Passing	Description
app	App	Required	—

Returns: readonly Id[].

goals

Registered domain Tools, optionally narrowed to ids.

AgentCatalogPorts.goals(ids?: readonly Id[]): readonly Intent[]

Registered domain Tools, optionally narrowed to ids.

Parameter	Type	Passing	Description
ids	readonly Id[] | undefined	Optional	—

Returns: readonly Intent[].

scopes

Registered scopes for the given Tool ids (all scopes when omitted).

AgentCatalogPorts.scopes(ids?: readonly Id[]): readonly Scope[]

Registered scopes for the given Tool ids (all scopes when omitted).

Parameter	Type	Passing	Description
ids	readonly Id[] | undefined	Optional	—

Returns: readonly Scope[].

currentTask

Task accepted for this request, if any.

AgentCatalogPorts.currentTask(app: App): CatalogTask<Id> | undefined

Task accepted for this request, if any.

Parameter	Type	Passing	Description
app	App	Required	—

Returns: CatalogTask<Id> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
goalId	Id	Required	Read-only. See the type definition and usage context.
scopeId	string | null | undefined	Optional	Read-only. Selected scope; null or undefined means a scope has not been chosen yet.

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

• CatalogGoal
• CatalogScope
• CatalogTask
• CatalogTool
• DescribedTool