# defineAgent

Reference for agent orchestration and side lifecycle bindings

## Signature

```typescript
import { defineAgent } from '@standardagents/spec';

export default defineAgent({
  name: 'support_agent',
  sideA: { prompt: 'support_prompt' },
  sideB: { human: true },
});
```

## AgentDefinition (first pass)

```typescript
interface AgentDefinition {
  name: string;
  title?: string;
  description?: string;
  icon?: string;
  maxSessionTurns?: number;
  primary?: boolean;
  exposeAsTool?: boolean;
  toolDescription?: string;
  hooks?: string[];
  env?: Record<string, string>;
  sideA: SideConfig;
  sideB: SideConfig;
}

interface SessionToolBinding {
  name: string;
  messageProperty?: string;
  attachmentsProperty?: string;
}

type SideConfig = HumanSide | PromptSide | HandlerSide;

interface HumanSide {
  human: true;
  label?: string;
}

interface PromptSide {
  prompt: string;
  label?: string;
  subagents?: SubagentRelationship[];
  stopOnResponse?: boolean;
  stopTool?: string;
  stopToolResponseProperty?: string;
  maxSteps?: number;

  // Lifecycle bindings
  sessionStop?: SessionToolBinding;
  sessionFail?: SessionToolBinding;
  sessionStatus?: SessionToolBinding;
}

interface HandlerSide {
  handler: string;
  label?: string;
  subagents?: SubagentRelationship[];
}
```

The canonical types are exported from `@standardagents/spec`:

```typescript
import type {
  SideConfig,
  HumanSide,
  PromptSide,
  HandlerSide,
} from '@standardagents/spec';
```

## Key Behavior

- Both sides are required. Each side declares exactly one backing: `human`, `prompt`, or `handler`.
- An exposed agent in a prompt's `tools` array performs a handoff in the current thread. Its human-backed side must match the thread's conversational surface.
- Declare persistent child relationships in the owning agent side's `subagents` array.
- `sessionStop` and `sessionFail` are terminal lifecycle outcomes.
- `sessionStatus` updates status without terminating execution.
- Lifecycle bindings reference tools in the side prompt's `tools` array.
- `stopOnResponse` defaults to `true`.

Session bindings require object form. `messageProperty` maps a tool argument to lifecycle message text. `attachmentsProperty` maps attachment paths.

```typescript
sideA: {
  prompt: 'orchestrator',
  subagents: [{ agent: 'topdown_asset_subagent', blocking: true }],
}
```

## Example: prompt × human

```typescript
defineAgent({
  name: 'support_agent',
  sideA: {
    prompt: 'support_prompt',
    stopOnResponse: true,
  },
  sideB: { human: true },
});
```

## Example: prompt × prompt subagent

```typescript
defineAgent({
  name: 'topdown_asset_subagent',
  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 agents with two prompt-backed sides.
- Keep lifecycle tool payloads concise and explicit.
- Import `defineAgent` and the other define functions from `@standardagents/spec`. A definition then depends on the specification package only.

## Related

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