Agents

Composition utilities

import { agent, isAgent, createCompositions } from '@crux/core/agent'

// Pre-bound versions from adapters:
import { parallel, pipeline, consensus, agent } from '@crux/ai'

agent(config)

Bundle a prompt with optional model and tools into a frozen agent instance.

Returns: Agent<TOwnInput, TOutput, TContexts> — frozen object with _tag: 'Agent'

isAgent(value)

Type guard — returns true if the value is an Agent instance created by agent().

parallel(options)

Run multiple agents concurrently and return typed results as a named record.

Returns: ParallelResult

In continue mode, each entry in settled is a SettledResult<AgentResult>:

• { status: 'success', value: AgentResult }
• { status: 'error', error: Error }

pipeline(options)

Chain agents sequentially with typed data flow between immediate steps via a context accumulator. Use flow() when you need suspend/resume or durable gates.

Agent step (inline object):

Plain function step (inline object):

Returns: PipelineResult

consensus(options)

Run multiple agents and determine a winner via voting.

Returns: ConsensusResult

Throws ConsensusError when quorum is not met. The error has .votes and .quorum properties.

AgentResult

AgentExecutor

SDK-agnostic executor interface. Each adapter implements this to bridge agents to their SDK's generate(). Used by createCompositions(executor) to create pre-bound composition functions.

type AgentExecutor = (agent: Agent, options: ExecuteOptions) => Promise<AgentResult>

createCompositions(executor)

Factory that creates adapter-bound parallel, pipeline, and consensus functions. Called internally by each adapter package.

createFakeAgentExecutor(config?)

A conformant in-memory AgentExecutor for testing how compositions drive the executor without an SDK (the agent-layer analogue of the resolver fakes). Exported from @crux/core/agent and the package root.

import { createFakeAgentExecutor, createPipeline } from '@crux/core/agent'

const executor = createFakeAgentExecutor({
  agents: {
    reviewer: { output: { score: 0.9 } },           // return output
    triage: { transfer: 'billing', reason: 'fees' }, // drive a swarm handoff
    flaky: { throws: 'LLM unavailable' },            // exercise an error path
  },
  fallback: 'echo', // unconfigured agents echo `{ _agent, _input }`
})

await createPipeline(executor)({ context: { seed: 1 }, model: 'm', steps: [{ name: 'r', agent: reviewer }] })

// Every invocation is recorded for assertions:
executor.calls[0].options.input        // { seed: 1 }
executor.calls[0].resolvedModel        // agent.model ?? options.model
executor.calls[0].executionContext     // ambient context observed per call

A Behavior is { output }, { transfer, reason } (executes the generated transfer_to_<id> tool), or { throws }; non-throwing forms may carry usage. A Resolver is (agent, options, callIndex) => Behavior for call-order-dependent fakes (e.g. consensus voters). The returned executor exposes a readonly calls array of { agent, options, resolvedModel, executionContext }.

Building-block primitives

import { blackboard, handoff, delegate } from '@crux/core/agent'

blackboard(config)

Shared typed state for multi-agent coordination.

Returns: Blackboard<T>

Use a board directly in prompt use when the agent should see and update shared state:

prompt({
  use: [board], // context + focused tools
})

Use board.asContext() for context-only injection, and board.asTools() when you want manual tool selection.

Focused tools pattern. .asTools() returns an object of individual tools. Pick which to expose based on the agent's role:

const board = blackboard({ id: 'shared', schema: mySchema, store })

// Read-only agent — can observe shared state but not modify it
const { readBlackboard } = board.asTools()
prompt({ tools: { readBlackboard } })

// Full access agent — can read and write
prompt({ tools: board.asTools() })

When a prompt uses more than one blackboard directly, give each board a prefix:

const research = blackboard({ id: 'research', schema, tools: { prefix: 'research' } })
const writing = blackboard({ id: 'writing', schema, tools: { prefix: 'writing' } })

prompt({ use: [research, writing] })
// readResearchBlackboard, writeResearchBlackboard, readWritingBlackboard, ...

Override descriptions for domain-specific language:

const { readBlackboard, writeBlackboard } = board.asTools()
const tools = {
  getSharedState: { ...readBlackboard, description: 'Read the current analysis results from the shared workspace.' },
  updateSharedState: { ...writeBlackboard, description: 'Write your analysis results to the shared workspace.' },
}

handoff(config)

Structured context transfer between agents. Supports stateless (in-process) and stored (distributed) modes.

Returns: HandoffInstance<TInput, TOutput>

delegate(config)

Orchestration wrapper combining handoff + subagent execution.

Generic parameters: delegate<TArgs, THandoffInput, THandoffOutput, TCtx>

TCtx defaults to unknown. When specified, both execute and .run() enforce the typed context — useful for threading framework-specific data (action context, project IDs, etc.).

Returns: Delegate<TArgs, TInput, TOutput, TCtx>

Focused tools pattern. .asTools() returns { delegate } — a single focused tool for triggering the delegation. Override the description to match your domain:

const researchDelegate = delegate({
  id: 'research',
  argsSchema: z.object({ topic: z.string() }),
  handoff: researchHandoff,
  execute: async (args) => runResearchAgent(args),
})

// Default: generic "delegate" tool name
prompt({ tools: researchDelegate.asTools() })

// Custom: rename and describe for your domain
const { delegate } = researchDelegate.asTools()
prompt({
  tools: {
    requestResearch: {
      ...delegate,
      description: 'Assign a research task to the research team. Provide the topic to investigate.',
    },
  },
})

DelegateResult:

Three-layer validation: argsSchema → handoff.inputSchema → handoff.outputSchema

Instrumentation

All primitives emit instrumentation events automatically:

Types

import type {
  // Composition
  Agent, AgentConfig, AgentLike,
  AgentExecutor, AgentResult, ExecuteOptions,
  ParallelOptions, ParallelResult, SettledResult,
  PipelineResult,
  ConsensusOptions, ConsensusResult,
  // Building blocks
  Blackboard, BlackboardConfig,
  HandoffInstance, HandoffConfig, HandoffPayload,
  Delegate, DelegateConfig, DelegateResult,
} from '@crux/core/agent'

import { ConsensusError } from '@crux/core/agent'

Related

• Guide: Agents
• Guide: Compositions
• Cookbook: Research pipeline