View as MarkdownPlain text for this page Open in ChatGPTQuestions about this page Open in ClaudeQuestions about this page

defineAgent

Reference for agent orchestration and side lifecycle bindings

Signature

import { defineAgent } from '@standardagents/spec';

export default defineAgent({
  name: 'support_agent',
  sideA: { prompt: 'support_prompt' },
  sideB: { human: true },
});

AgentDefinition (first pass)

interface AgentDefinition {
  name: string;
  title?: string;
  description?: string;
  icon?: string;
  maxSessionTurns?: number;
  primary?: boolean;
  exposeAsTool?: boolean;
  toolDescription?: string;
  hooks?: string[];
  env?: Record<string, string>;
  sideA: SideConfig;
  sideB: SideConfig;
}

interface SessionToolBinding {
  name: string;
  messageProperty?: string;
  attachmentsProperty?: string;
}

type SideConfig = HumanSide | PromptSide | HandlerSide;

interface HumanSide {
  human: true;
  label?: string;
}

interface PromptSide {
  prompt: string;
  label?: string;
  subagents?: SubagentRelationship[];
  stopOnResponse?: boolean;
  stopTool?: string;
  stopToolResponseProperty?: string;
  maxSteps?: number;

  // Lifecycle bindings
  sessionStop?: SessionToolBinding;
  sessionFail?: SessionToolBinding;
  sessionStatus?: SessionToolBinding;
}

interface HandlerSide {
  handler: string;
  label?: string;
  subagents?: SubagentRelationship[];
}

The canonical types are exported from @standardagents/spec:

import type {
  SideConfig,
  HumanSide,
  PromptSide,
  HandlerSide,
} from '@standardagents/spec';

Key Behavior

Both sides are required. Each side declares exactly one backing: human, prompt, or handler.
An exposed agent in a prompt's tools array performs a handoff in the current thread. Its human-backed side must match the thread's conversational surface.
Declare persistent child relationships in the owning agent side's subagents array.
sessionStop and sessionFail are terminal lifecycle outcomes.
sessionStatus updates status without terminating execution.
Lifecycle bindings reference tools in the side prompt's tools array.
stopOnResponse defaults to true.

Session bindings require object form. messageProperty maps a tool argument to lifecycle message text. attachmentsProperty maps attachment paths.

sideA: {
  prompt: 'orchestrator',
  subagents: [{ agent: 'topdown_asset_subagent', blocking: true }],
}

Example: prompt × human

defineAgent({
  name: 'support_agent',
  sideA: {
    prompt: 'support_prompt',
    stopOnResponse: true,
  },
  sideB: { human: true },
});

Example: prompt × prompt subagent

defineAgent({
  name: 'topdown_asset_subagent',
  maxSessionTurns: 60,
  exposeAsTool: true,
  toolDescription: 'Generate and QA top-down assets.',
  sideA: {
    label: 'Asset Worker',
    prompt: 'topdown_asset_subagent_worker',
    stopOnResponse: true,
    sessionFail: {
      name: 'fail_topdown_asset',
      messageProperty: 'failure_summary',
      attachmentsProperty: 'attachments',
    },
  },
  sideB: {
    label: 'QA Reviewer',
    prompt: 'topdown_asset_subagent_reviewer',
    stopOnResponse: false,
    sessionStop: {
      name: 'approve_topdown_asset',
      messageProperty: 'approval_summary',
      attachmentsProperty: 'approved_assets',
    },
    sessionStatus: {
      name: 'set_topdown_asset_status',
      messageProperty: 'status',
    },
  },
});

Notes

Set maxSessionTurns on agents with two prompt-backed sides.
Keep lifecycle tool payloads concise and explicit.
Import defineAgent and the other define functions from @standardagents/spec. A definition then depends on the specification package only.