Skip to main content

​
Overview

defineAgent creates an agent configuration that defines the structure and behavior of AI-powered conversations. 
import { defineAgent } from '@standardagents/builder';

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

​
Type Definition

function defineAgent(config: AgentConfig): AgentConfig;

interface AgentConfig {
  name: string;
  type: 'ai_human' | 'dual_ai';
  title?: string;
  exposeAsTool?: boolean;
  toolDescription?: string;
  tags?: string[];
  maxSessionTurns?: number;
  sideA: SideConfig;
  sideB?: SideConfig;
}

interface SideConfig {
  label?: string;
  prompt: StandardAgents.Prompts;
  stopOnResponse?: boolean;
  stopTool?: string;
  stopToolResponseProperty?: string;
  endConversationTool?: string;
  maxTurns?: number;
}

​
Parameters

​
name
string
required
Unique identifier for this agent. Used in API routes and thread creation.
​
type
'ai_human' | 'dual_ai'
required
Agent type:
  • ai_human - AI assistant converses with a human user
  • dual_ai - Two AI participants converse with each other
​
title
string
Human-readable display title for the agent.
​
exposeAsTool
boolean
default:"false"
When true, this agent can be called as a tool by other agents for handoffs.
​
toolDescription
string
Description shown when agent is available as a tool. Required if exposeAsTool is true.
​
tags
string[]
Array of tags for filtering and routing.
​
maxSessionTurns
number
Maximum total turns for the entire conversation. Required for dual_ai agents.
​
sideA
SideConfig
required
Configuration for the primary AI participant.
​
sideB
SideConfig
Configuration for the secondary participant. Required for dual_ai agents.

​
SideConfig

​
sideA.label
string
Display name for this side (shown in logs and UI).
​
sideA.prompt
StandardAgents.Prompts
required
The prompt configuration to use. Must be defined in agents/prompts/.
​
sideA.stopOnResponse
boolean
default:"false"
Stop the turn when AI returns text without calling tools.
​
sideA.stopTool
string
Stop the turn when this specific tool is called.
​
sideA.stopToolResponseProperty
string
Property from stop tool result to use as response.
​
sideA.endConversationTool
string
End the entire conversation when this tool is called.
​
sideA.maxTurns
number
Maximum turns allowed for this side.

​
Return Value

Returns the same AgentConfig object passed in, enabling the build system to register it.

​
Examples

​
Simple AI-Human Agent

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

​
Customer Support Agent

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

​
Workflow Agent

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,
  },
});

​
Dual AI Agent

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,
  },
});

​
Agent as Tool (Handoff)

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

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

​
Stop Conditions

Stop conditions control when turns and conversations end:
ConditionDescription
stopOnResponse: trueStop when AI returns text without tools
stopTool: 'name'Stop when specific tool is called
maxTurns: NStop after N turns by this side
endConversationTool: 'name'End entire conversation when tool is called

​
Retry Sequence with Fallbacks

When a request fails:
  1. Primary model (attempt 1) → Failed? Retry…
  2. Primary model (attempt 2) → Failed? Try fallback…
  3. Fallback 1 (attempt 1) → Failed? Retry…
  4. Continue until success or all fallbacks exhausted

​
File Location

Agents are auto-discovered from agents/agents/: 
agents/
└── agents/
    ├── support_agent.ts
    ├── checkout_agent.ts
    └── debate_agent.ts
Requirements:
  • Use snake_case for file names
  • One agent per file
  • Default export required

​
Generated Types

After running the build, StandardAgents.Agents type is generated for type-safe references.