Agent
Agents
Agent orchestration patterns, execution engine, handoff validation, memory management, and agent discovery.
Import
import {
// Orchestration patterns
sequential,
parallel,
hybrid,
hierarchical,
swarm,
type OrchestrationPattern,
type OrchestrationStep,
type OrchestrationPlan,
// Execution
executeOrchestration,
validateHandoff,
validateHandoffContract,
simpleSchemaValidate,
type StepResult,
type OrchestrationResult,
type TaskFn,
type ExecutionOptions,
type HandoffValidationError,
// Memory
createAgentMemory,
createFileLongTermMemory,
createFileEpisodicMemory,
createInMemoryMemoryStore,
type AgentMemory,
type MemoryStore,
type MemoryEntry,
type WorkingMemory,
type ShortTermMemory,
type LongTermMemory,
type EpisodicMemory,
// Discovery
createAgentDiscovery,
matchAgentBySkill,
createStubAgentCardFetcher,
type AgentDiscovery,
type AgentFilter,
type A2AAgentCard,
} from '@ai-sdlc/reference';Orchestration Patterns
Five pattern builders create OrchestrationPlan instances from AgentRole resources.
sequential(agents)
Build a plan where agents execute in order. Each step depends on the previous.
function sequential(agents: AgentRole[]): OrchestrationPlan;const plan = sequential([codeAgent, reviewAgent, deployAgent]);
// implement → review → deployparallel(agents)
Build a plan where all agents execute concurrently with no dependencies.
function parallel(agents: AgentRole[]): OrchestrationPlan;hybrid(dispatcher, specialists)
Build a plan where a dispatcher agent routes work to specialist agents.
function hybrid(dispatcher: AgentRole, specialists: AgentRole[]): OrchestrationPlan;hierarchical(manager, workers)
Build a plan where a manager agent delegates to worker agents.
function hierarchical(manager: AgentRole, workers: AgentRole[]): OrchestrationPlan;swarm(agents)
Build a plan from agents that reference each other via handoff declarations. Dependencies are derived from handoff targets.
function swarm(agents: AgentRole[]): OrchestrationPlan;Execution
executeOrchestration(plan, agents, taskFn, options?)
Execute an orchestration plan. Steps run concurrently when their dependencies are satisfied.
function executeOrchestration(
plan: OrchestrationPlan,
agents: Map<string, AgentRole>,
taskFn: TaskFn,
options?: ExecutionOptions,
): Promise<OrchestrationResult>;Parameters:
plan-- AnOrchestrationPlanfrom one of the pattern buildersagents-- Map of agent name toAgentRoleresourcetaskFn-- Function that executes a single agent step:(agent: AgentRole, input?: unknown) => Promise<unknown>options-- Optional authorization hook and audit log
Returns: OrchestrationResult with plan, stepResults[], and success boolean.
import { sequential, executeOrchestration } from '@ai-sdlc/reference';
const plan = sequential([codeAgent, reviewAgent]);
const agents = new Map([
['code-agent', codeAgent],
['review-agent', reviewAgent],
]);
const result = await executeOrchestration(plan, agents, async (agent, input) => {
console.log(`Executing ${agent.metadata.name}`);
return { status: 'done', output: `${agent.metadata.name} completed` };
});
console.log('Success:', result.success);
for (const step of result.stepResults) {
console.log(` ${step.agent}: ${step.state}`);
}ExecutionOptions
interface ExecutionOptions {
authorize?: AuthorizationHook;
auditLog?: AuditLog;
}When authorize is provided, each step is checked before execution. Denied steps fail with an authorization error and are recorded in the audit log.
Handoff Validation
validateHandoff(from, to, payload, schemaResolver?)
Validate a handoff between two agents. Checks that a handoff declaration exists and that all required fields are present in the payload.
function validateHandoff(
from: AgentRole,
to: AgentRole,
payload: Record<string, unknown>,
schemaResolver?: SchemaResolver,
): HandoffValidationError | null;Returns null if valid, or a HandoffValidationError describing the problem.
const error = validateHandoff(codeAgent, reviewAgent, {
prUrl: 'https://github.com/org/repo/pull/42',
testResults: { passed: 100, failed: 0, skipped: 2 },
});
if (error) {
console.error(`Handoff failed: ${error.message}`);
}validateHandoffContract(handoff, payload, schemaResolver?)
Validate a handoff payload against its contract schema.
simpleSchemaValidate(schema, data, path?)
Lightweight structural JSON Schema validator. Checks type, required, and properties without a full AJV dependency.
Memory
createAgentMemory(options)
Create a multi-tier agent memory system with working, short-term, long-term, and episodic tiers.
createFileLongTermMemory(dir)
Create a file-backed long-term memory store that persists across sessions.
createFileEpisodicMemory(dir)
Create a file-backed episodic memory store for recording agent experiences.
createInMemoryMemoryStore()
Create an in-memory store for testing.
Memory Types
interface MemoryEntry {
key: string;
value: unknown;
timestamp: string;
metadata?: Record<string, unknown>;
}
interface AgentMemory {
working: WorkingMemory;
shortTerm: ShortTermMemory;
longTerm: LongTermMemory;
episodic: EpisodicMemory;
}Discovery
createAgentDiscovery(fetcher?)
Create an agent discovery service for finding agents by skill, role, or capability.
matchAgentBySkill(agent, query)
Check if an agent matches a skill-based query.
createStubAgentCardFetcher(cards)
Create a stub fetcher that returns predetermined A2A agent cards (for testing).