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'

Agent entries in tools

An Agent's tools map may contain direct child Agent values alongside ordinary Tools:

const parent = agent({
  id: "parent",
  prompt: parentPrompt,
  tools: { research: researchAgent },
});

research is the exported model-tool name. researchAgent.id remains the child's identity and Work target; it does not rename the Tool. Crux uses the child Agent's description, falling back to its Prompt's description. If neither exists, preparation throws Foreground Agent tool "research" requires an Agent or Prompt description. before provider dispatch or child Work acceptance. Crux does not synthesize a description.

There is no text-input shortcut. Tool arguments are validated before Work acceptance, so invalid input creates no child Work. Direct Agent entries are bound after authored and call-level tools are merged and before ordinary Tool preparation. The winning map entry follows the same middleware, approval, and guardrail path as any other Tool, under its map-key name; no separate collision or approval behavior is introduced.

Execution accepts exactly one foreground child Work and awaits it. The Tool result is the child's exact validated structured or multimodal output, not an AgentResult, summary, transcript, or execution handle. The child runs with only its own Agent definition—its prompt, use, and tools—and receives only its declared input. Parent-only and sibling tools, parent history and request details, and parent runtime or control handles are not inherited.

An ambient Work attachment links the child to its execution ancestry. Without one, the child receives cancellation linkage only. In either case, that linkage does not grant authority over the parent. Parent cancellation propagates through the child Work boundary; child failure, cancellation, or timeout rejects the ordinary Tool execution and follows the normal Tool-loop error path.

For child Agents that can continue independently, see Backgroundable Agent Work.

Each direct foreground child invocation opens a distinct nested agent.run below its ordinary tool.call, in the same trace as the parent. The child agent.run boundary projects only the authored agentId and invoked-Agent definition reference; it does not project prompt, input, output, tool history, request, model, control, or handle data. Local Run Detail preserves the parent/Tool/child hierarchy, and Devtools renders the child as its own Agent row. Descendant generation and Tool evidence continue to follow the configured observability capture and redaction policy.

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