Skip to main content

​
What Are Agents?

Agents define conversation orchestration:
  • ai_human: AI side responds to user messages
  • dual_ai: side A and side B alternate until stop conditions are met
Agents reference prompts, define stop semantics, and can be exposed as callable tools.

​
Basic Example

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

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

​
Side Configuration

sideA is required. sideB is required for dual_ai. Common side fields:
  • prompt
  • label
  • stopOnResponse
  • stopTool
  • stopToolResponseProperty
  • maxSteps
Session lifecycle fields:
  • sessionStop
  • sessionFail
  • sessionStatus
Lifecycle fields support:
  • string form: 'tool_name'
  • object form: { name, messageProperty?, attachmentsProperty? }
Object form is recommended for subagent workflows because it explicitly maps which tool args become parent-visible message text and attachments.

​
Exposing Agents as Tools

defineAgent({
  name: 'billing_specialist',
  type: 'ai_human',
  exposeAsTool: true,
  toolDescription: 'Handle billing and payment escalations.',
  sideA: {
    prompt: 'billing_prompt',
    stopOnResponse: true,
  },
});
Behavior depends on agent type:
  • callable ai_human: handoff-style tool interaction
  • callable dual_ai: subagent execution in child thread

​
dual_ai as Subagents

When a dual_ai agent is called via prompt tools, AgentBuilder can run it as a child thread with:
  • isolated message history/logs/filesystem
  • parent/child linkage and child registry
  • blocking/non-blocking behavior
  • resumable/non-resumable lifecycle
For resumable subagents, runtime lifecycle tools (subagent_create, subagent_message) are injected by the runtime, not user-defined in agents/tools.

​
Example: Worker + Reviewer

defineAgent({
  name: 'asset_subagent',
  type: 'dual_ai',
  maxSessionTurns: 40,
  exposeAsTool: true,
  toolDescription: 'Generate and QA top-down assets.',
  sideA: {
    label: 'Worker',
    prompt: 'asset_worker',
    stopOnResponse: true,
    sessionFail: {
      name: 'fail_asset',
      messageProperty: 'summary',
      attachmentsProperty: 'attachments',
    },
  },
  sideB: {
    label: 'Reviewer',
    prompt: 'asset_reviewer',
    stopOnResponse: false,
    sessionStop: {
      name: 'approve_asset',
      messageProperty: 'summary',
      attachmentsProperty: 'attachments',
    },
    sessionStatus: {
      name: 'asset_status',
      messageProperty: 'status',
    },
  },
});

​
Best Practices

  • Always set maxSessionTurns for dual_ai
  • Use sessionStop / sessionFail for explicit terminal outcomes
  • Use object-form lifecycle bindings when payload shape matters
  • Keep side prompts specialized (side_a production, side_b QA)