Agents

What Are Agents?

Agents in AgentBuilder define the structure and behavior of AI-powered conversations. Think of an agent as a blueprint that determines:

Who’s talking: Is it AI ↔ Human or AI ↔ AI?
What they know: Which prompts guide the conversation
What they can do: Which tools they have access to
When to stop: When turns or conversations should end

Agents are file-based and auto-discovered. Just create a TypeScript file in agents/agents/ and export your agent definition—no manual registration needed!

Quick Start

Create your first agent in agents/agents/support_agent.ts:

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

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

This creates an agent where:

An AI (side A) converses with a human user
The AI uses the customer_support prompt
The AI’s turn ends when it sends a text response

That’s it! Your agent is now available throughout your application. The framework automatically discovers it and makes it available via the generated AgentBuilder.Agents type.

Agent Types

AgentBuilder supports two fundamental types of agents:

ai_human (Human-AI Conversations)

The most common agent type. An AI assistant converses with a human user.Perfect for:

Customer support chatbots
Personal assistants
Q&A systems
Interactive tutorials

Example:

defineAgent({
  name: 'assistant',
  type: 'ai_human',
  sideA: {
    label: 'Assistant',
    prompt: 'helpful_assistant',
    stopOnResponse: true,
  },
});

dual_ai (AI-AI Conversations)

Two AI participants conversing with each other in turn-based fashion.Perfect for:

Debate simulations
Iterative refinement (writer ↔ critic)
Multi-perspective analysis
Evaluation loops

Example:

defineAgent({
  name: 'debate_agent',
  type: 'dual_ai',
  maxSessionTurns: 20,
  sideA: {
    label: 'Pro',
    prompt: 'debate_pro',
    stopOnResponse: false,
    maxTurns: 10,
  },
  sideB: {
    label: 'Con',
    prompt: 'debate_con',
    stopOnResponse: false,
    maxTurns: 10,
  },
});

Understanding Sides

Every agent has side A and optionally side B:

Side A (Required)

The primary AI participant. For ai_human agents, this is always the AI assistant.

sideA: {
  label: 'Support Agent',       // Display name
  prompt: 'support_prompt',     // Prompt to use
  stopOnResponse: true,         // Stop when returns text
  maxTurns: 25,                 // Maximum turns allowed
}

Side B (Optional)

Only required for dual_ai agents. For ai_human agents, side B represents the human user and doesn’t need configuration.

sideB: {
  label: 'Customer',
  prompt: 'customer_simulator',  // Only for dual_ai
  stopOnResponse: false,
  maxTurns: 20,
}

Stop Conditions

Stop conditions control when turns and conversations end. You can combine multiple conditions:

Text Response

Stop when AI returns text without calling tools

stopOnResponse: true

Specific Tool

Stop when a particular tool is called

stopTool: 'complete_checkout'

Max Turns

Stop after N turns by this side

maxTurns: 20

End Tool

End entire conversation when tool is called

endConversationTool: 'close_ticket'

Common Patterns

Simple Conversation

sideA: {
  stopOnResponse: true,  // Stop after each response
}

Multi-Step Workflow

sideA: {
  stopOnResponse: false,           // Don't stop on text
  stopTool: 'workflow_complete',   // Stop on specific tool
  maxTurns: 30,                    // Safety limit
}

Research Loop

sideA: {
  stopOnResponse: false,
  endConversationTool: 'submit_research',  // End when done
  maxTurns: 50,
}

Agent Handoffs

Agents can be exposed as tools, enabling specialized routing and handoffs:

// Specialist agent
defineAgent({
  name: 'billing_specialist',
  exposeAsTool: true,
  toolDescription: 'Hand off billing and payment issues to a specialist',
  sideA: {
    prompt: 'billing_expert',
    stopOnResponse: true,
  },
});

// Router agent that can hand off
defineAgent({
  name: 'support_router',
  sideA: {
    prompt: 'router_prompt',  // Has 'billing_specialist' in tools array
    stopOnResponse: true,
  },
});

When an LLM calls an agent tool, execution pauses, the specialist agent runs to completion, and the result is returned to the calling agent.

Common Use Cases

Customer Support

defineAgent({
  name: 'support_agent',
  type: 'ai_human',
  sideA: {
    label: 'Support',
    prompt: 'customer_support',
    stopOnResponse: true,
    endConversationTool: 'resolve_issue',
  },
  tags: ['support', 'customer-facing'],
});

Workflow Assistant

defineAgent({
  name: 'checkout_agent',
  type: 'ai_human',
  sideA: {
    label: 'Checkout Assistant',
    prompt: 'checkout_flow',
    stopOnResponse: false,
    stopTool: 'confirm_order',
    stopToolResponseProperty: 'orderId',
    endConversationTool: 'complete_checkout',
    maxTurns: 30,
  },
});

defineAgent({
  name: 'content_refiner',
  type: 'dual_ai',
  maxSessionTurns: 10,
  sideA: {
    label: 'Writer',
    prompt: 'content_writer',
    maxTurns: 5,
  },
  sideB: {
    label: 'Editor',
    prompt: 'content_editor',
    maxTurns: 5,
    endConversationTool: 'approve_content',
  },
});

Best Practices

Use Descriptive Names

Choose clear, purpose-driven names:✅ Good: customer_support_agent, billing_specialist, data_analyst❌ Avoid: agent1, bot, helper

Set Safety Limits

Always include maxTurns to prevent runaway conversations:

sideA: {
  maxTurns: 25,  // Reasonable limit for most conversations
}

For dual_ai, also set maxSessionTurns:

maxSessionTurns: 30,  // Total conversation limit

Choose Appropriate Stop Conditions

Match stop conditions to your use case:

Conversational agents: stopOnResponse: true
Workflow agents: stopTool: 'workflow_complete'
Research agents: endConversationTool: 'submit_results'

Use Labels for Clarity

Labels make logs and UI more readable:

sideA: {
  label: 'Customer Support Agent',  // Clear in logs
  prompt: 'support_prompt',
}

Organize with Tags

Use tags for filtering and routing:

defineAgent({
  name: 'billing_support',
  tags: ['support', 'billing', 'tier-2', 'financial'],
  // ...
});

Getting Started

Core Concepts

User Interfaces

What Are Agents?

Quick Start

Agent Types

Understanding Sides

Side A (Required)

Side B (Optional)

Stop Conditions

Text Response

Specific Tool

Max Turns

End Tool

Common Patterns

Agent Handoffs

Common Use Cases

Customer Support

Workflow Assistant

Iterative Refinement

Best Practices

Execution Flow

ai_human Flow

dual_ai Flow

Next Steps

Prompts

Tools

API Reference

Examples

Getting Started

Core Concepts

User Interfaces

​What Are Agents?

​Quick Start

​Agent Types

​Understanding Sides

​Side A (Required)

​Side B (Optional)

​Stop Conditions

Text Response

Specific Tool

Max Turns

End Tool

​Common Patterns

​Agent Handoffs

​Common Use Cases

​Customer Support

​Workflow Assistant

​Iterative Refinement

​Best Practices

​Execution Flow

​ai_human Flow

​dual_ai Flow

​Next Steps

Prompts

Tools

API Reference

Examples

What Are Agents?

Quick Start

Agent Types

Understanding Sides

Side A (Required)

Side B (Optional)

Stop Conditions

Common Patterns

Agent Handoffs

Common Use Cases

Customer Support

Workflow Assistant

Iterative Refinement

Best Practices

Execution Flow

ai_human Flow

dual_ai Flow

Next Steps