Agents

Composition utilities

import { agent, isAgent, createCompositions } from "@use-crux/core/agent";

// Pre-bound versions from adapters:
import { parallel, pipeline, consensus, agent } from "@use-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<AgentResultPayload>

Executors are adapter/application ports and return ID-free payload facts. Core finalizes the public AgentResult at agent.run. Composition parent results point at their own composition.* spans while nested agent results retain their child spans. See Operation Result Correlation.

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 @use-crux/core/agent and the package root.

import { createFakeAgentExecutor, createPipeline } from "@use-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 "@use-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. Each delegation validates data at three points:

1. argsSchema: validates what the LLM provides when calling the tool
2. handoff.inputSchema: validates the subagent's return value
3. handoff.outputSchema: transforms and validates the final data for the consumer

Instrumentation

All primitives emit instrumentation events automatically:

Events are correlated to the enclosing trace when emitted within a generate() or agent step. For handoffs, canonical traces also attach the validated handoff input to inspection.input and the prepared handoff payload to inspection.output.

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 "@use-crux/core/agent";

import { ConsensusError } from "@use-crux/core/agent";

Related

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