Agents

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. subagent_create.arguments is validated from the receiving child side’s prompt schema and persists with the child thread as ThreadState.arguments. Both child sides can read it and use its top-level keys as prompt variables.

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)

Getting Started

Core Concepts

User Interfaces

Providers

What Are Agents?

Basic Example

Side Configuration

Exposing Agents as Tools

dual_ai as Subagents

Example: Worker + Reviewer

Best Practices

​What Are Agents?

​Basic Example

​Side Configuration

​Exposing Agents as Tools

​dual_ai as Subagents

​Example: Worker + Reviewer

​Best Practices

​Related Docs

What Are Agents?

Basic Example

Side Configuration

Exposing Agents as Tools

dual_ai as Subagents

Example: Worker + Reviewer

Best Practices

Related Docs