Skip to main content

​
Signature

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

export default defineAgent({
  // AgentDefinition
});

​
AgentDefinition (first pass)

interface AgentDefinition {
  name: string;
  type?: 'ai_human' | 'dual_ai';
  title?: string;
  description?: string;
  icon?: string;
  maxSessionTurns?: number;
  exposeAsTool?: boolean;
  toolDescription?: string;
  hooks?: string[];
  tenvs?: Record<string, unknown>;
  sideA: SideConfig;
  sideB?: SideConfig;
}

type SessionToolBinding =
  | string
  | {
      name: string;
      messageProperty?: string;
      attachmentsProperty?: string;
    };

interface SideConfig {
  prompt: string;
  label?: string;
  stopOnResponse?: boolean;
  stopTool?: string;
  stopToolResponseProperty?: string;
  maxSteps?: number;

  // Preferred lifecycle bindings
  sessionStop?: SessionToolBinding;
  sessionFail?: SessionToolBinding;
  sessionStatus?: SessionToolBinding;

  // Legacy aliases
  endSessionTool?: string;
  failSessionTool?: string;
  statusTool?: string;
}

​
Key Behavior

  • ai_human tool exposure behaves like handoff-style agent calls.
  • dual_ai tool exposure can be used as subagent execution (configured in prompt tools).
  • sessionStop and sessionFail are terminal lifecycle outcomes.
  • sessionStatus updates status without terminating execution.
Object-form session bindings are recommended when you need explicit message/attachment field mapping for child -> parent payloads.

​
Example: ai_human

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

​
Example: dual_ai subagent

defineAgent({
  name: 'topdown_asset_subagent',
  type: 'dual_ai',
  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 dual_ai agents.
  • Keep lifecycle tool payloads concise and explicit.
  • Prefer @standardagents/builder imports in AgentBuilder projects.