> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagentbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# defineAgent

> Reference for agent orchestration and side lifecycle bindings

## Signature

```typescript theme={null}
import { defineAgent } from '@standardagents/builder';

export default defineAgent({
  // AgentDefinition
});
```

## AgentDefinition (first pass)

```typescript theme={null}
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;
}
```

## 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

```typescript theme={null}
defineAgent({
  name: 'support_agent',
  type: 'ai_human',
  sideA: {
    prompt: 'support_prompt',
    stopOnResponse: true,
  },
});
```

## Example: dual\_ai subagent

```typescript theme={null}
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.

## Related

* [definePrompt](/api-reference/define/prompt)
* [Subagents](/core-concepts/subagents)