# Struere Documentation — SDK

> Filtered section from the Struere docs. Full docs: https://docs.struere.dev/llms.txt

---

## SDK Overview

> TypeScript SDK for defining agents, data, roles, and automations

Source: https://docs.struere.dev/sdk/overview.md

The Struere SDK provides 6 TypeScript definition functions — defineAgent, defineData, defineRole, defineTrigger, defineRouter, and defineTools — for configuring an entire AI agent system as code. Resources are upserted by slug on sync, with pre-sync validation of agent references, entity type references, and integration requirements.

## Installation

```bash
bun add struere
```

Initialize a new project:

```bash
bunx struere init
```

This scaffolds the following project structure:

```
my-org/
├── struere.json
├── agents/
│   └── scheduler.ts
├── entity-types/
│   └── teacher.ts
├── roles/
│   └── admin.ts
├── triggers/
│   └── notify-on-session.ts
└── tools/
    └── index.ts
```

The `struere.json` file stores organization metadata:

```json
{
  "version": "2.0",
  "organization": {
    "id": "org_abc123",
    "slug": "acme-corp",
    "name": "Acme Corp"
  }
}
```

## SDK Exports

The SDK exports five definition functions, each responsible for a specific resource type:

```typescript
import {
  defineAgent,
  defineTools,
  defineData,
  defineRole,
  defineTrigger,
  defineRouter
} from 'struere'
```

| Function | Purpose | File Location |
|----------|---------|---------------|
| `defineAgent` | Create and configure AI agent definitions | `agents/*.ts` |
| `defineData` | Define data type schemas | `entity-types/*.ts` |
| `defineRole` | Create roles with policies, scope rules, and field masks | `roles/*.ts` |
| `defineTrigger` | Define automation rules | `triggers/*.ts` |
| `defineRouter` | Define conversation routing rules | `routers/*.ts` |
| `defineTools` | Create custom tool handlers | `tools/index.ts` |

Each definition file exports a default using its corresponding function:

```typescript
import { defineAgent } from 'struere'

export default defineAgent({
  name: "Scheduler",
  slug: "scheduler",
  version: "0.1.0",
  systemPrompt: "You are a scheduling assistant.",
  tools: ["entity.create", "entity.query", "event.emit"],
})
```

## Type Exports

The SDK also exports all TypeScript types for use in your project:

```typescript
import type {
  AgentConfig,
  ModelConfig,
  DataTypeConfig,
  JSONSchema,
  JSONSchemaProperty,
  RoleConfig,
  PolicyConfig,
  ScopeRuleConfig,
  FieldMaskConfig,
  TriggerConfig,
  TriggerAction,
  ToolReference,
  ToolParameters,
  ParameterDefinition,
  ToolHandler,
  ToolContext,
  StruereSDK,
  StruereProject,
  SyncPayload,
  SyncState,
} from 'struere'
```

## Organization-Centric Architecture

Struere uses a single-project approach where one repository defines the entire organization's AI infrastructure:

- **Agents** share data types, roles, and tools across the organization
- **Data types** define the domain schema once and are available to all agents
- **Roles** enforce access control consistently across all agents and API access
- **Automations** automate workflows that fire from any mutation source (dashboard, agents, or API)
- **Tools** are org-level resources in the `customTools` table, referenced by any agent by name

The `struere dev` command watches all directories and syncs changes to the Convex backend in real time. The `struere deploy` command pushes all agents to production.

## Sync Workflow

During development, all resources are synced as a single payload:

```typescript
{
  agents: [...],
  entityTypes: [...],
  roles: [...],
  triggers: [...],
  tools: [...]
}
```

Resources are upserted by their `slug` (agents, data types, triggers) or `name` (roles), so renaming a slug creates a new resource rather than updating the existing one.

---

## defineData

> Define data type schemas for your domain

Source: https://docs.struere.dev/sdk/define-data.md

The `defineData` function creates and validates data type schema definitions. Each data type is defined in its own file under the `entity-types/` directory.

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Teacher",
  slug: "teacher",
  schema: {
    type: "object",
    properties: {
      name: { type: "string", description: "Full name" },
      email: { type: "string", format: "email", description: "Email address" },
      subjects: {
        type: "array",
        items: { type: "string" },
        description: "Subjects they can teach",
      },
      hourlyRate: { type: "number", description: "Rate per hour in cents" },
    },
    required: ["name", "email"],
  },
  searchFields: ["name", "email"],
  displayConfig: {
    titleField: "name",
    subtitleField: "email",
  },
})
```

## EntityTypeConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Display name for the data type |
| `slug` | `string` | Yes | URL-safe identifier, used in API queries and tool calls |
| `schema` | `JSONSchema` | Yes | JSON Schema definition for the data |
| `searchFields` | `string[]` | No | Fields indexed for text search (defaults to `[]`) |
| `displayConfig` | `object` | No | Controls how records are displayed in the dashboard |
| `boundToRole` | `string` | No | Binds this data type to a role name for automatic user linking |
| `userIdField` | `string` | No | Field that stores the Clerk user ID (defaults to `"userId"` when `boundToRole` is set) |

### Validation

`defineData` throws errors if:

- `name`, `slug`, or `schema` is missing
- `schema.type` is not `"object"`
- Any nested object property is missing `properties`
- `boundToRole` is an empty string
- `userIdField` is set without `boundToRole`

## JSON Schema

Data type schemas use the JSON Schema format with the following type system:

```typescript
interface JSONSchema {
  type: 'object'
  properties: Record<string, JSONSchemaProperty>
  required?: string[]
}

interface JSONSchemaProperty {
  type: 'string' | 'number' | 'boolean' | 'array' | 'object'
  description?: string
  format?: string
  enum?: string[]
  items?: JSONSchemaProperty
  properties?: Record<string, JSONSchemaProperty>
  required?: string[]
  references?: string
}
```

The root schema must always be `type: "object"`. Nested objects must declare their `properties`.

### Supported Property Types

**String fields:**

```typescript
{
  name: { type: "string", description: "Full name" },
  email: { type: "string", format: "email" },
  status: {
    type: "string",
    enum: ["active", "inactive", "suspended"],
  },
}
```

**Number fields:**

```typescript
{
  hourlyRate: { type: "number", description: "Rate in cents" },
  age: { type: "number" },
}
```

**Boolean fields:**

```typescript
{
  isActive: { type: "boolean", description: "Whether the record is active" },
}
```

**Array fields:**

```typescript
{
  subjects: {
    type: "array",
    items: { type: "string" },
    description: "List of subjects",
  },
  tags: {
    type: "array",
    items: { type: "string", enum: ["math", "science", "english"] },
  },
}
```

**Nested object fields:**

```typescript
{
  address: {
    type: "object",
    properties: {
      street: { type: "string" },
      city: { type: "string" },
      postalCode: { type: "string" },
    },
    required: ["street", "city"],
  },
}
```

## References

Fields with `references` enforce foreign key constraints. When an entity is created or updated, any field with `references` is validated to ensure the referenced entity exists.

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Session",
  slug: "session",
  schema: {
    type: "object",
    properties: {
      studentId: { type: "string", references: "student" },
      teacherId: { type: "string", references: "teacher" },
      startTime: { type: "number" },
      duration: { type: "number" },
      subject: { type: "string" },
    },
    required: ["studentId", "teacherId", "startTime", "duration"],
  },
})
```

When the agent calls `entity.create` or `entity.update` with a `studentId` or `teacherId` value, the platform validates that:

- The referenced entity exists
- The referenced entity is not deleted
- The referenced entity belongs to the same organization and environment
- The referenced entity is of the correct entity type (e.g., `studentId` must reference a `student` entity)

If any validation fails, the operation throws an error identifying the invalid reference field.

## Display Configuration

The `displayConfig` field controls how records appear in the dashboard:

```typescript
displayConfig: {
  titleField: "name",
  subtitleField: "email",
  descriptionField: "notes",
}
```

| Field | Description |
|-------|-------------|
| `titleField` | Primary display field (shown as heading) |
| `subtitleField` | Secondary display field (shown below title) |
| `descriptionField` | Extended description field |

## Search Fields

The `searchFields` array specifies which fields are indexed for text search via `entity.query`:

```typescript
searchFields: ["name", "email", "phone"]
```

When an agent uses `entity.query` with a search term, only these fields are matched.

## Role Binding

The `boundToRole` and `userIdField` fields create an automatic link between a data type and a user role. When a user with the bound role logs in, they are associated with the matching record:

```typescript
export default defineData({
  name: "Teacher",
  slug: "teacher",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      email: { type: "string", format: "email" },
      userId: { type: "string", description: "Clerk user ID" },
    },
    required: ["name", "email"],
  },
  boundToRole: "teacher",
  userIdField: "userId",
})
```

When `boundToRole` is set and `userIdField` is omitted, it defaults to `"userId"`.

## Filtering entities

Entity queries (via the Data API, `entity.query` tool, or the JS client) accept a `filters` object. Two rules govern which fields are filterable:

- **Top-level fields are restricted to indexed columns.** The Data API only accepts top-level filter fields that are indexed on the entity table (e.g., `matchId` when present, plus a small set of system fields). Filtering on a non-indexed top-level field returns `400 Bad Request` with the list of fields that ARE queryable.
- **Use `data.<fieldName>` for everything in the JSON payload.** Domain fields declared in your `schema.properties` live inside the entity's `data` blob. Reference them as `data.status`, `data.teamId`, `data.guardianId`, etc. These filters apply in-memory after the indexed scan.

```typescript
await struere.data.query('session', {
  filters: {
    'data.status': 'scheduled',
    'data.teacherId': 'usr_123',
  },
})
```

### Foot-gun: top-level `status` is the entity lifecycle column

The top-level `status` field on an entity is the platform-managed lifecycle column (`active`, `archived`, `deleted`). If your data type also defines a domain `status` field (e.g., `pending`, `confirmed`, `paid`), they are not the same column.

A top-level `status` filter is **rejected** with `400 Bad Request`. The error tells you to use `data.status` instead:

```typescript
await struere.data.query('session', {
  filters: { 'data.status': 'scheduled' },
})
```

If you really do want to filter the lifecycle column, pass `status` as a top-level option (alongside `filters`, `limit`, `cursor`) — not as a key inside `filters`.

### Foot-gun: filtering on a non-indexed top-level field

If you write `filters: { teacherId: 'usr_123' }` and `teacherId` is a domain field stored in the JSON payload, the API returns `400 Bad Request` listing the indexed fields it accepts. The fix is the same: prefix with `data.`:

```typescript
await struere.data.query('session', {
  filters: { 'data.teacherId': 'usr_123' },
})
```

## Unsupported JSON Schema features

`defineData` accepts a deliberate subset of JSON Schema. The fields shown in the type definition above (`type`, `description`, `format`, `enum`, `items`, `properties`, `required`, `references`) are the only ones recognised — anything else will be rejected by the SDK type or silently dropped.

- `additionalProperties` — schemas are closed. To persist a `Record<id, X>` shape, reshape it into an array of records with an `id` field.
- `oneOf` / `anyOf` / `allOf` — model variants as a discriminated union via an `enum` field, then branch on that field in your code.
- `if` / `then` / `else` — conditional shapes are not supported. Express conditional logic in the application layer or split into separate entity types.
- `$ref` / `definitions` — schemas are inlined. Copy shared shapes into each entity type that needs them.
- `pattern`, `minimum`, `maximum`, `minLength`, `maxLength`, `multipleOf`, etc. — only `enum` and `format` constrain values at the schema level. Enforce additional validation in your code or via tools.

## Full Examples

### Student Data Type

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Student",
  slug: "student",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      grade: { type: "string" },
      subjects: {
        type: "array",
        items: { type: "string" },
      },
      notes: { type: "string" },
      guardianId: { type: "string" },
      preferredTeacherId: { type: "string" },
    },
    required: ["name"],
  },
  searchFields: ["name"],
  displayConfig: {
    titleField: "name",
    subtitleField: "grade",
  },
})
```

### Session Data Type

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Session",
  slug: "session",
  schema: {
    type: "object",
    properties: {
      teacherId: { type: "string" },
      studentId: { type: "string" },
      guardianId: { type: "string" },
      startTime: { type: "number", description: "Unix timestamp" },
      duration: { type: "number", description: "Duration in minutes" },
      subject: { type: "string" },
      status: {
        type: "string",
        enum: [
          "pending_payment",
          "scheduled",
          "in_progress",
          "completed",
          "cancelled",
          "no_show",
        ],
      },
      notes: { type: "string" },
      teacherReport: { type: "string" },
    },
    required: ["teacherId", "studentId", "guardianId", "startTime", "duration"],
  },
  searchFields: ["subject"],
  displayConfig: {
    titleField: "subject",
    subtitleField: "status",
  },
})
```

### Entitlement Data Type (Credits System)

```typescript
import { defineData } from 'struere'

export default defineData({
  name: "Entitlement",
  slug: "entitlement",
  schema: {
    type: "object",
    properties: {
      guardianId: { type: "string" },
      studentId: { type: "string" },
      totalCredits: { type: "number" },
      remainingCredits: { type: "number" },
      expiresAt: { type: "number", description: "Unix timestamp" },
    },
    required: ["guardianId", "studentId", "totalCredits", "remainingCredits"],
  },
  displayConfig: {
    titleField: "remainingCredits",
    subtitleField: "totalCredits",
  },
})
```

---

## defineRole

> Create roles with policies, scope rules, and field masks

Source: https://docs.struere.dev/sdk/define-role.md

The `defineRole` function creates roles with access control policies, row-level scope rules, and column-level field masks. Each role is defined in its own file under the `roles/` directory.

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "teacher",
  description: "Tutors who conduct sessions",
  agentAccess: ["scheduling-agent", "student-portal"],
  policies: [
    { resource: "session", actions: ["list", "read", "update"], effect: "allow" },
    { resource: "student", actions: ["list", "read"], effect: "allow" },
    { resource: "payment", actions: ["*"], effect: "deny" },
  ],
  scopeRules: [
    { entityType: "session", field: "data.teacherId", operator: "eq", value: "actor.userId" },
  ],
  fieldMasks: [
    { entityType: "session", fieldPath: "data.paymentId", maskType: "hide" },
    { entityType: "student", fieldPath: "data.guardianId", maskType: "hide" },
  ],
})
```

## RoleConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | `string` | No | Unique role identifier (lowercase, alphanumeric + hyphens). Derived from `name` if omitted. Will be required in a future major version — declare it explicitly on new roles. |
| `name` | `string` | Yes | Display label for the role |
| `description` | `string` | No | Human-readable description |
| `agentAccess` | `string[]` | No | Agent slugs this role can access conversations for (defaults to `[]`) |
| `policies` | `PolicyConfig[]` | Yes | Access control rules (at least one required) |
| `scopeRules` | `ScopeRuleConfig[]` | No | Row-level security filters (defaults to `[]`) |
| `fieldMasks` | `FieldMaskConfig[]` | No | Column-level security masks (defaults to `[]`) |

### Slug vs name

`slug` is the role's identity. It is what agents reference in `defineAgent({ roles: ['coach'] })` and what scope rules and dashboard ACLs match against. `name` is the human-readable label shown in the dashboard.

```typescript
import { defineRole } from 'struere'

export default defineRole({
  slug: 'coach',
  name: 'Coach',
  policies: [
    { resource: 'player', actions: ['read', 'update'], effect: 'allow' },
  ],
})
```

When `slug` is omitted, it is derived from `name` (lowercased, non-alphanumeric replaced with hyphens). Existing roles without a `slug` continue to work — they get one auto-derived on next sync. New roles should declare `slug` explicitly; it will be required in a future major version.

See [`defineAgent`](./define-agent#roles-and-permissions) for how agents reference roles by slug.

### Validation

`defineRole` throws errors if:

- `name` is missing
- `policies` is empty or missing
- Any policy is missing `resource`, `actions`, or `effect`
- `agentAccess` contains empty strings

## PolicyConfig

Policies define what actions a role can perform on which resources.

```typescript
interface PolicyConfig {
  resource: string
  actions: string[]
  effect: 'allow' | 'deny'
}
```

| Field | Type | Description |
|-------|------|-------------|
| `resource` | `string` | Data type slug or built-in resource (`users`) the policy applies to |
| `actions` | `string[]` | Allowed values: `"create"`, `"read"`, `"update"`, `"delete"`, `"list"`, or `"*"` for all |
| `effect` | `'allow' \| 'deny'` | Whether to allow or deny the specified actions |

### Policy Evaluation

The permission engine evaluates policies with a **deny-overrides-allow** model:

1. All policies matching the resource and action are collected
2. If any matching policy has `effect: "deny"`, access is denied
3. If at least one policy has `effect: "allow"` and none deny, access is allowed
4. If no policies match, access is denied

```typescript
policies: [
  { resource: "session", actions: ["list", "read", "update"], effect: "allow" },
  { resource: "session", actions: ["delete"], effect: "deny" },
]
```

In this example, the role can list, read, and update sessions but cannot delete them. Even if another role grants delete access, this deny policy overrides it.

### Wildcard Actions

Use `"*"` to match all actions on a resource:

```typescript
{ resource: "session", actions: ["*"], effect: "allow" }
```

This grants create, read, update, delete, and list access.

### Deny-All Pattern

Block all access to a resource:

```typescript
{ resource: "payment", actions: ["*"], effect: "deny" }
```

## ScopeRuleConfig

Scope rules implement row-level security by filtering which entities a role can see.

```typescript
interface ScopeRuleConfig {
  entityType: string
  field: string
  operator: 'eq' | 'neq' | 'in' | 'contains'
  value: string
}
```

| Field | Type | Description |
|-------|------|-------------|
| `entityType` | `string` | Data type slug to filter |
| `field` | `string` | Dot-notation path to the entity field (e.g., `"data.teacherId"`) |
| `operator` | `string` | Comparison operator |
| `value` | `string` | Value to compare against; supports `"actor.userId"` for dynamic resolution |

### Dynamic Value Resolution

The `value` field supports the special prefix `actor.` to reference the current actor's properties at runtime:

- `"actor.userId"` resolves to the authenticated user's ID
- This enables scope rules like "a teacher can only see their own sessions"

### Scope Rule Examples

Teacher sees only sessions where they are the assigned teacher:

```typescript
scopeRules: [
  {
    entityType: "session",
    field: "data.teacherId",
    operator: "eq",
    value: "actor.userId",
  },
]
```

Guardian sees only their own children:

```typescript
scopeRules: [
  {
    entityType: "student",
    field: "data.guardianId",
    operator: "eq",
    value: "actor.userId",
  },
  {
    entityType: "session",
    field: "data.guardianId",
    operator: "eq",
    value: "actor.userId",
  },
]
```

### Operators

| Operator | Description |
|----------|-------------|
| `eq` | Field equals value |
| `neq` | Field does not equal value |
| `in` | Field is contained in value (array) |
| `contains` | Field contains value (substring or array member) |

> **Gotcha:** Use `neq`, not `ne`. Other operators (`ne`, `nin`, `gt`, etc.) silently fail to match. See [Platform Gotchas](/platform/gotchas) for details.

## FieldMaskConfig

Field masks implement column-level security by hiding or redacting specific fields.

```typescript
interface FieldMaskConfig {
  entityType: string
  fieldPath: string
  maskType: 'hide' | 'redact'
  maskConfig?: Record<string, unknown>
}
```

| Field | Type | Description |
|-------|------|-------------|
| `entityType` | `string` | Data type slug to mask |
| `fieldPath` | `string` | Dot-notation path to the field (e.g., `"data.paymentId"`) |
| `maskType` | `'hide' \| 'redact'` | `hide` removes the field entirely; `redact` replaces the value |
| `maskConfig` | `object` | Additional configuration for redaction behavior |

### Mask Types

**Hide** removes the field from the response entirely:

```typescript
{ entityType: "student", fieldPath: "data.guardianId", maskType: "hide" }
```

**Redact** replaces the field value while keeping the key present:

```typescript
{ entityType: "payment", fieldPath: "data.amount", maskType: "redact", maskConfig: { replacement: "***" } }
```

### Allowlist Strategy

Field masks use an **allowlist strategy**, which means new fields added to a data type are hidden by default until explicitly allowed. This is a fail-safe approach that prevents accidental data exposure.

> **Gotcha:** Adding a new field to a data type means it's hidden by default for any role with a field mask on that type — review masks when you change schemas. See [Platform Gotchas](/platform/gotchas) for details.

## Agent Access

The `agentAccess` field controls which agents' conversations a role can see in the dashboard. Members with a role can only view and reply to threads belonging to the listed agents. Admins bypass this restriction and see all conversations.

```typescript
agentAccess: ["sales-agent", "support-agent"]
```

### `agentAccess` vs being assigned to an agent's `roles`

A role document defines two independent relationships with agents. They are not the same thing.

| Relationship | Field | What it does |
|--------------|-------|--------------|
| Dashboard ACL | `agentAccess` on the role | Lets human users with this role view and reply to threads belonging to the listed agents in the dashboard. **Does not grant the agent any permissions.** |
| Permission inheritance | `roles` on the agent (see [`defineAgent`](./define-agent#roles-and-permissions)) | When the agent executes, it inherits this role's `policies`, `scopeRules`, and `fieldMasks`. The agent acts under those permissions. |

Same role doc, two different relationships. Pick the one(s) you need.

The example below uses both: humans assigned the `coach` role can chat with `coach-stats` in the dashboard (`agentAccess`), and the `coach-stats` agent itself inherits the role's policies and scope rules at runtime (when it lists `roles: ["coach"]` in `defineAgent`).

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "coach",
  policies: [
    { resource: "player", actions: ["read", "update"], effect: "allow" },
  ],
  scopeRules: [
    { entityType: "player", field: "data.teamId", operator: "eq", value: "team-A" },
  ],
  agentAccess: ["coach-stats"],
})
```

For the full picture of how roles are granted to humans and agents and evaluated at runtime, see [Agent Permissions](../platform/agent-permissions).

| Behavior | Description |
|----------|-------------|
| Not set or empty | Role has no conversation access |
| List of slugs | Role can view threads for those agents |
| Multiple roles | Access is the union of all assigned roles' `agentAccess` slugs |
| Admin users | Bypass `agentAccess` entirely — see all conversations |

Agent slugs are resolved at query time. If a slug doesn't match an existing agent, it is silently skipped. When the agent is created later, access is automatically granted.

Members cannot start new conversations — they can only view and reply to existing threads for their allowed agents.

## Full Examples

### Admin Role

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "admin",
  description: "Full access to all resources",
  policies: [
    { resource: "teacher", actions: ["*"], effect: "allow" },
    { resource: "student", actions: ["*"], effect: "allow" },
    { resource: "guardian", actions: ["*"], effect: "allow" },
    { resource: "session", actions: ["*"], effect: "allow" },
    { resource: "payment", actions: ["*"], effect: "allow" },
    { resource: "entitlement", actions: ["*"], effect: "allow" },
  ],
})
```

### Teacher Role

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "teacher",
  description: "Tutors who conduct sessions",
  agentAccess: ["scheduling-agent", "student-portal"],
  policies: [
    { resource: "session", actions: ["list", "read", "update"], effect: "allow" },
    { resource: "student", actions: ["list", "read"], effect: "allow" },
    { resource: "teacher", actions: ["read", "update"], effect: "allow" },
    { resource: "payment", actions: ["*"], effect: "deny" },
    { resource: "entitlement", actions: ["*"], effect: "deny" },
  ],
  scopeRules: [
    { entityType: "session", field: "data.teacherId", operator: "eq", value: "actor.userId" },
    { entityType: "teacher", field: "data.userId", operator: "eq", value: "actor.userId" },
  ],
  fieldMasks: [
    { entityType: "session", fieldPath: "data.paymentId", maskType: "hide" },
    { entityType: "student", fieldPath: "data.guardianId", maskType: "hide" },
  ],
})
```

### Guardian Role

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "guardian",
  description: "Parents or guardians of students",
  agentAccess: ["parent-portal"],
  policies: [
    { resource: "student", actions: ["list", "read", "update"], effect: "allow" },
    { resource: "session", actions: ["list", "read"], effect: "allow" },
    { resource: "payment", actions: ["list", "read"], effect: "allow" },
    { resource: "entitlement", actions: ["list", "read"], effect: "allow" },
    { resource: "teacher", actions: ["*"], effect: "deny" },
  ],
  scopeRules: [
    { entityType: "student", field: "data.guardianId", operator: "eq", value: "actor.userId" },
    { entityType: "session", field: "data.guardianId", operator: "eq", value: "actor.userId" },
    { entityType: "payment", field: "data.guardianId", operator: "eq", value: "actor.userId" },
    { entityType: "entitlement", field: "data.guardianId", operator: "eq", value: "actor.userId" },
  ],
  fieldMasks: [
    { entityType: "session", fieldPath: "data.teacherReport", maskType: "hide" },
  ],
})
```

### Team Lead Role

```typescript
import { defineRole } from 'struere'

export default defineRole({
  name: "team-lead",
  description: "Team lead with member management access",
  agentAccess: ["support-agent", "sales-agent"],
  policies: [
    { resource: "users", actions: ["create", "update", "delete"], effect: "allow" },
    { resource: "session", actions: ["list", "read", "update"], effect: "allow" },
    { resource: "customer", actions: ["list", "read"], effect: "allow" },
  ],
  scopeRules: [
    { entityType: "session", field: "data.teamLeadId", operator: "eq", value: "actor.userId" },
  ],
})
```

The `resource: "users"` policies grant this role permission to invite new members (`create`), assign internal roles to team members (`update`), and remove non-admin members (`delete`) from the Team page in the dashboard. Non-admins can only invite as `org:member`. Team leads cannot promote users to admin or modify admin users.

---

## defineAgent

> Create and configure AI agent definitions

Source: https://docs.struere.dev/sdk/define-agent.md

The `defineAgent` function creates and validates an AI agent configuration. Each agent is defined in its own file under the `agents/` directory.

```typescript
import { defineAgent } from 'struere'

export default defineAgent({
  name: "Scheduler",
  slug: "scheduler",
  version: "0.1.0",
  systemPrompt: "You are a scheduling assistant for {{organizationName}}.",
  model: {
    model: "openai/gpt-5-mini",
  },
  tools: [
    "entity.create",
    "entity.query",
    "entity.update",
    "agent.chat",
  ],
})
```

## AgentConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Display name for the agent |
| `slug` | `string` | Yes | URL-safe identifier, used for API routing (`/v1/agents/:slug/chat`) |
| `version` | `string` | Yes | Semantic version string (e.g., `"0.1.0"`) |
| `systemPrompt` | `string \| (() => string \| Promise<string>)` | Yes | System prompt with template variable support |
| `description` | `string` | No | Human-readable description |
| `model` | `ModelConfig` | No | LLM model and inference settings |
| `tools` | `string[]` | No | Array of tool names (built-in and custom) |
| `roles` | `string[]` | No | Role names whose policies, scope rules, and field masks the agent inherits at runtime |
| `firstMessageSuggestions` | `string[]` | No | Clickable suggestion chips shown in the chat empty state |
| `threadContextParams` | `ThreadContextParam[]` | No | Schema for expected thread context parameters (see below) |

### Validation

`defineAgent` throws an error if `name`, `version`, or `systemPrompt` is missing.

## Model Configuration

The `model` field configures which LLM provider and model the agent uses. If omitted, defaults to `openai/gpt-5-mini` with temperature `0.7` and maxTokens `4096`.

```typescript
interface ModelConfig {
  model: string
  temperature?: number
  maxTokens?: number
  reasoning?: {
    enabled?: boolean
    effort?: 'minimal' | 'low' | 'medium' | 'high'
    budgetTokens?: number
    hideFromResponse?: boolean
  }
}
```

Model IDs use `"provider/model-name"` format (e.g., `"openai/gpt-5-mini"`, `"anthropic/claude-sonnet-4-6"`).

> **Gotcha:** Bare model names like `"gpt-5-mini"` (without the `openai/` prefix) are rejected at runtime — always include the provider. See [Platform Gotchas](/platform/gotchas) for details.

```typescript
export default defineAgent({
  name: "Analyst",
  slug: "analyst",
  version: "1.0.0",
  systemPrompt: "You are a precise data analyst.",
  model: {
    model: "openai/gpt-5-mini",
    temperature: 0.3,
    maxTokens: 8192,
  },
  tools: ["entity.query"],
})
```

To enable chain-of-thought reasoning:

```typescript
export default defineAgent({
  name: "Research Assistant",
  slug: "research-assistant",
  version: "1.0.0",
  systemPrompt: "You are a research assistant.",
  model: {
    model: "openai/gpt-5-mini",
    reasoning: {
      effort: "high",
    },
  },
  tools: [],
})
```

For the full list of providers, models, pricing, and reasoning options, see [Model Configuration](../reference/model-configuration).

## Tools

The `tools` field is an array of tool name strings referencing both [built-in tools](../tools/built-in-tools) and [custom tools](../tools/custom-tools) defined via `defineTools`. Custom tools are org-level resources — agents reference them by name rather than embedding full tool definitions. Tools marked as `templateOnly: true` are available to all agents' system prompts automatically and do not need to be listed here.

```typescript
tools: [
  "entity.create",
  "entity.query",
  "send_email",
]
```

## Roles and Permissions

The `roles` field declares which roles' policies, scope rules, and field masks the agent inherits when it executes. Roles are referenced by name and must exist in `roles/`.

```typescript
export default defineAgent({
  name: "Coach Stats",
  slug: "coach-stats",
  version: "0.1.0",
  systemPrompt: "You report stats for Team A players.",
  model: { model: "openai/gpt-5-mini" },
  tools: ["entity.query"],
  roles: ["team-a-coach"],
})
```

When this agent runs, every `entity.query`, `entity.update`, and other permission-checked tool call is evaluated against the union of the listed roles' policies, scope rules, and field masks. The agent sees only the rows and fields its roles allow.

If `roles` is empty or missing, the agent falls back to the singleton `agent` role — existing zero-config agents keep working unchanged.

This is distinct from [`agentAccess`](../sdk/define-role#agent-access) on a role, which is a dashboard ACL (which users can chat with which agents) and grants the agent no permissions. See [Agent Permissions](../platform/agent-permissions) for the end-to-end model.

## First Message Suggestions

The `firstMessageSuggestions` field provides an array of strings displayed as clickable chips in the chat empty state. When a user clicks a suggestion, it sends that text as their first message.

```typescript
export default defineAgent({
  name: "Support",
  slug: "support",
  version: "0.1.0",
  systemPrompt: "You are a support agent for {{organizationName}}.",
  model: { model: "openai/gpt-5-mini" },
  tools: ["entity.query"],
  firstMessageSuggestions: [
    "What can you help me with?",
    "Show me recent activity",
    "Create a new record",
  ],
})
```

Suggestions appear in all chat surfaces: the dashboard dev chat, public chat, embedded widget, and the chat sidebar on the agent detail page. Agents without suggestions show the default "Start a conversation" empty state.

## Thread Context Parameters

The `threadContextParams` field declares what context parameters your agent expects from callers. When defined, the backend validates incoming params — checking required fields, enforcing types, and dropping unknown params.

```typescript
interface ThreadContextParam {
  name: string
  type: 'string' | 'number' | 'boolean'
  required?: boolean
  description?: string
}
```

```typescript
export default defineAgent({
  name: "Support",
  slug: "support",
  version: "0.1.0",
  systemPrompt: `You are a support agent for {{organizationName}}.
Customer: {{threadContext.params.email}}
Plan: {{threadContext.params.plan}}`,
  model: { model: "openai/gpt-5-mini" },
  tools: ["entity.query"],
  threadContextParams: [
    { name: "email", type: "string", required: true, description: "Customer email" },
    { name: "plan", type: "string", description: "Subscription plan" },
  ],
})
```

These parameters are passed differently depending on the channel:

| Channel | How params are passed |
|---------|----------------------|
| **Widget** | URL parameters on the `<script>` tag (e.g., `?email=jane@example.com&plan=pro`) |
| **API** | `threadContext.params` in the JSON request body |
| **WhatsApp** | Automatically populated from the inbound message (phone number, contact name) |
| **Dashboard** | Editable in the system prompt compile panel (auto-detected from `{{threadContext.params.*}}` references if not explicitly declared) |

The channel itself is always available via `{{threadContext.channel}}`.

### Auto-Populated Parameters by Channel

Each channel automatically populates certain parameters on the thread:

| Channel | Auto-populated params |
|---------|----------------------|
| **WhatsApp** | `phoneNumber` (sender's phone with country code), `contactName` (WhatsApp profile name, if available) |
| **API** | Whatever the caller sends in `threadContext.params` |
| **Widget** | URL parameters from the embed script tag |
| **Dashboard** | User-provided values in the compile panel |

### WhatsApp Example

An agent that identifies the sender by their phone number:

```typescript
export default defineAgent({
  name: "Teacher Assistant",
  slug: "teacher-assistant",
  version: "0.1.0",
  systemPrompt: `You are a teaching assistant for {{organizationName}}.

The current sender's phone number is {{threadContext.params.phoneNumber}}.
Their WhatsApp name is {{threadContext.params.contactName}}.
Channel: {{threadContext.channel}}

Use the phone number to look up the teacher's entity and personalize your responses.`,
  model: { model: "openai/gpt-5-mini" },
  tools: ["entity.query", "entity.update"],
  threadContextParams: [
    { name: "phoneNumber", type: "string", description: "Sender phone number" },
    { name: "contactName", type: "string", description: "WhatsApp display name" },
  ],
})

## System Prompt Templates

System prompts support `{{variable}}` syntax for dynamic context injection at runtime. Common variables include `{{organizationName}}`, `{{currentTime}}`, `{{agentName}}`, and `{{entityTypes}}`.

```typescript
systemPrompt: `You are {{agentName}}, a coordinator for {{organizationName}}.
Current time: {{currentTime}}

Available data types: {{entityTypes}}`
```

For the full variable reference and embedded query syntax, see [System Prompt Templates](../tools/system-prompt-templates).

---

## defineTrigger

> Define event-driven automation rules

Source: https://docs.struere.dev/sdk/define-trigger.md

The `defineTrigger` function creates automation rules that fire on entity events or cron schedules. Each automation is defined in its own file under the `triggers/` directory.

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: "Notify on New Session",
  slug: "notify-on-session",
  on: {
    entityType: "session",
    action: "created",
    condition: { "data.status": "scheduled" },
  },
  actions: [
    {
      tool: "entity.get",
      args: { id: "{{trigger.data.teacherId}}" },
      as: "teacher",
    },
    {
      tool: "whatsapp.send",
      args: {
        to: "{{steps.teacher.data.phone}}",
        text: "New session scheduled: {{trigger.data.subject}}",
      },
    },
  ],
})
```

## TriggerConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Display name for the automation |
| `slug` | `string` | Yes | Unique identifier for the automation |
| `description` | `string` | No | Human-readable description |
| `on` | `object` | Yes | Event or schedule configuration that activates the automation |
| `on.entityType` | `string` | Entity triggers | Data type slug to watch |
| `on.action` | `'created' \| 'updated' \| 'deleted'` | Entity triggers | Entity lifecycle event |
| `on.condition` | `object` | No | Optional filter on entity data fields (entity triggers only) |
| `on.schedule` | `string` | Cron triggers | Cron expression (5 fields: minute hour day-of-month month day-of-week) |
| `on.timezone` | `string` | No | IANA timezone for the cron schedule (default: `'UTC'`) |
| `schedule` | `TriggerSchedule` | No | Delay or schedule execution for a future time (entity triggers only) |
| `retry` | `TriggerRetry` | No | Retry configuration for failed executions |
| `actions` | `TriggerAction[]` | Yes | Ordered list of steps to execute (at least one required) |

The `on` field accepts one of two configurations:

- **Entity triggers**: `{ entityType, action, condition? }` — fires on data mutations
- **Cron triggers**: `{ schedule, timezone? }` — fires on a cron schedule

### Validation

`defineTrigger` throws errors if:

- `name`, `slug`, or `on` is missing
- For entity triggers: `on.entityType` is missing or `on.action` is not one of `"created"`, `"updated"`, `"deleted"`
- For cron triggers: `on.schedule` is not a valid 5-field cron expression
- `actions` is empty or missing
- Any action is missing `tool` or has non-object `args`
- `schedule.delay` and `schedule.at` are both set
- `schedule.delay` is not a positive number
- `retry.maxAttempts` is less than 1
- `retry.backoffMs` is not a positive number

## TriggerAction

Each action step executes a tool with the given arguments.

```typescript
interface TriggerAction {
  tool: string
  args: Record<string, unknown>
  as?: string
}
```

| Field | Type | Description |
|-------|------|-------------|
| `tool` | `string` | Any built-in tool (e.g., `entity.create`, `whatsapp.send`, `agent.chat`) or custom tool name |
| `args` | `object` | Arguments passed to the tool, supports template variables |
| `as` | `string` | Optional name for referencing this step's result in later steps |

Actions execute in order. If any action fails, the automation stops (fail-fast behavior).

### Available Tools

| Category | Tools |
|----------|-------|
| Entity | `entity.create`, `entity.get`, `entity.query`, `entity.update`, `entity.delete` |
| Calendar | `calendar.list`, `calendar.create`, `calendar.update`, `calendar.delete`, `calendar.freeBusy` |
| WhatsApp | `whatsapp.send`, `whatsapp.sendTemplate`, `whatsapp.sendInteractive`, `whatsapp.sendMedia`, `whatsapp.listTemplates`, `whatsapp.getConversation`, `whatsapp.getStatus` |
| Agent | `agent.chat` |
| Custom | Any custom tool defined in the `tools/` directory |

## Template Variables

Automation action arguments support `{{variable}}` template syntax for dynamic value resolution.

### Automation Context Variables

| Variable | Description |
|----------|-------------|
| `{{trigger.entityId}}` | ID of the record that activated the automation |
| `{{trigger.entityType}}` | Data type slug |
| `{{trigger.action}}` | The action that occurred (`"created"`, `"updated"`, `"deleted"`) |
| `{{trigger.data.X}}` | Field `X` from the entity's current data |
| `{{trigger.previousData.X}}` | Field `X` from the entity's data before the update (only for `"updated"` actions) |

### Step Reference Variables

| Variable | Description |
|----------|-------------|
| `{{steps.NAME.X}}` | Access field `X` from the result of step named `NAME` (set via `as` field) |

### Template Example

```typescript
actions: [
  {
    tool: "entity.get",
    args: { id: "{{trigger.data.teacherId}}" },
    as: "teacher",
  },
  {
    tool: "entity.get",
    args: { id: "{{trigger.data.guardianId}}" },
    as: "guardian",
  },
  {
    tool: "whatsapp.send",
    args: {
      to: "{{steps.guardian.data.phone}}",
      text: "Session booked with {{steps.teacher.data.name}} for {{trigger.data.subject}}",
    },
  },
]
```

## Cron Triggers

Cron triggers fire on a recurring schedule instead of entity events. Use the `on.schedule` field with a standard 5-field cron expression.

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: 'Teacher Weekly Reminder',
  slug: 'teacher-weekly-reminder',
  on: {
    schedule: '0 20 * * 0',
    timezone: 'America/Santiago',
  },
  actions: [
    {
      tool: 'send_teacher_weekly_schedules',
      args: {},
    },
  ],
})
```

### Cron Expression Format

```
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *
```

| Syntax | Meaning | Example |
|--------|---------|---------|
| `*` | Every value | `* * * * *` (every minute) |
| `5` | Specific value | `0 5 * * *` (5am daily) |
| `1-5` | Range | `0 9 * * 1-5` (9am weekdays) |
| `*/5` | Step | `*/5 * * * *` (every 5 minutes) |
| `1,3,5` | List | `0 0 1,15 * *` (1st and 15th of month) |

### Timezone

The `timezone` field accepts any IANA timezone identifier. If omitted, the schedule runs in UTC.

```typescript
on: {
  schedule: '0 9 * * 1-5',
  timezone: 'America/New_York',
}
```

### Execution

- Cron triggers are checked every minute by the platform
- They do not have entity context (`trigger.entityId`, `trigger.data`, etc. are not available)
- The `schedule` field (delay/at) is not applicable to cron triggers
- Successful executions emit `trigger.executed` events
- Failed executions emit `trigger.failed` events

## Conditions

The `on.condition` field filters which data mutations activate the automation. Only records whose data matches all condition fields will activate the automation:

```typescript
on: {
  entityType: "session",
  action: "updated",
  condition: { "data.status": "completed" },
}
```

This automation only fires when a session is updated and its `status` field is `"completed"`.

### Transition Conditions

For `updated` actions, conditions can match against `previousData` to detect state transitions. This prevents automations from re-firing when a record is updated but hasn't actually changed state:

```typescript
on: {
  entityType: "session",
  action: "updated",
  condition: {
    "data.status": "scheduled",
    "previousData.status": "pending_payment",
  },
}
```

This fires only on the transition from `pending_payment` to `scheduled` — not when an already-scheduled session is rescheduled.

| Path prefix | Description | Available for |
|-------------|-------------|---------------|
| `data.*` | Current record data (after mutation) | `created`, `updated`, `deleted` |
| `previousData.*` | Record data before the mutation | `updated` only |

### Trigger Cascading

Entity mutations inside automation actions **do not cascade by default**. To allow an action to fire other automations, pass `cascade: true`:

```typescript
{
  tool: "entity.create",
  args: {
    type: "notification",
    data: { message: "Session confirmed" },
    cascade: true,
  },
}
```

Without `cascade: true`, entity writes from automations are silent. Supported on `entity.create`, `entity.update`, and `entity.delete`.

## Scheduled Automations

Automations can be scheduled to run at a future time instead of executing immediately.

```typescript
interface TriggerSchedule {
  delay?: number
  at?: string
  offset?: number
  cancelPrevious?: boolean
}
```

| Field | Type | Description |
|-------|------|-------------|
| `delay` | `number` | Delay in milliseconds before execution |
| `at` | `string` | Template expression resolving to an ISO timestamp or Unix timestamp |
| `offset` | `number` | Offset in milliseconds to add to the `at` time (can be negative) |
| `cancelPrevious` | `boolean` | Cancel any pending scheduled run for the same entity before scheduling |

`delay` and `at` are mutually exclusive.

### Schedule Examples

Send a reminder 1 hour before a session starts:

```typescript
export default defineTrigger({
  name: "Session Reminder",
  slug: "session-reminder",
  on: {
    entityType: "session",
    action: "created",
    condition: { "data.status": "scheduled" },
  },
  schedule: {
    at: "{{trigger.data.startTime}}",
    offset: -3600000,
    cancelPrevious: true,
  },
  actions: [
    {
      tool: "entity.get",
      args: { id: "{{trigger.data.guardianId}}" },
      as: "guardian",
    },
    {
      tool: "whatsapp.send",
      args: {
        to: "{{steps.guardian.data.phone}}",
        text: "Reminder: session starting in 1 hour for {{trigger.data.subject}}",
      },
    },
  ],
})
```

Delay notification by 5 minutes:

```typescript
schedule: {
  delay: 300000,
}
```

### Automation Runs

Scheduled automations create records in the `triggerRuns` table with status tracking:

| Status | Description |
|--------|-------------|
| `pending` | Scheduled but not yet executed |
| `running` | Currently executing |
| `completed` | Successfully finished |
| `failed` | Failed but may be retried |
| `dead` | Failed and exhausted all retry attempts |

## Retry Configuration

Failed automations can be retried with exponential backoff.

```typescript
interface TriggerRetry {
  maxAttempts?: number
  backoffMs?: number
}
```

| Field | Type | Description |
|-------|------|-------------|
| `maxAttempts` | `number` | Maximum number of retry attempts (minimum 1) |
| `backoffMs` | `number` | Base delay in milliseconds between retries |

```typescript
retry: {
  maxAttempts: 3,
  backoffMs: 5000,
}
```

This retries up to 3 times with 5-second base backoff between attempts.

## Execution Behavior

- Automations execute **asynchronously** (scheduled after the originating mutation completes)
- Automations run as the **system actor** with full permissions
- Actions execute in **fail-fast** order (first failure stops the chain)
- Successful automations emit a `trigger.executed` event
- Failed automations emit a `trigger.failed` event
- Automations fire from **all mutation sources**: dashboard CRUD, agent tool calls, and API mutations

## Full Examples

### Notify Guardian on Session Completion

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: "Notify on Completion",
  slug: "notify-on-completion",
  on: {
    entityType: "session",
    action: "updated",
    condition: { "data.status": "completed" },
  },
  actions: [
    {
      tool: "entity.get",
      args: { id: "{{trigger.data.guardianId}}" },
      as: "guardian",
    },
    {
      tool: "whatsapp.send",
      args: {
        to: "{{steps.guardian.data.phone}}",
        text: "Session completed: {{trigger.data.subject}}",
      },
    },
  ],
})
```

### Auto-Deduct Credits on Completion

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: "Deduct Credits",
  slug: "deduct-credits",
  on: {
    entityType: "session",
    action: "updated",
    condition: { "data.status": "completed" },
  },
  retry: {
    maxAttempts: 3,
    backoffMs: 2000,
  },
  actions: [
    {
      tool: "entity.query",
      args: {
        type: "entitlement",
        filters: { "data.studentId": "{{trigger.data.studentId}}" },
        limit: 1,
      },
      as: "entitlements",
    },
    {
      tool: "entity.update",
      args: {
        id: "{{trigger.entityId}}",
        data: { creditsDeducted: true },
      },
    },
  ],
})
```

### Scheduled Follow-Up

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: "Post-Session Follow-Up",
  slug: "post-session-followup",
  on: {
    entityType: "session",
    action: "updated",
    condition: { "data.status": "completed" },
  },
  schedule: {
    delay: 86400000,
  },
  retry: {
    maxAttempts: 2,
    backoffMs: 60000,
  },
  actions: [
    {
      tool: "agent.chat",
      args: {
        agent: "followup",
        message: "Send a follow-up for session {{trigger.entityId}}",
        context: {
          teacherId: "{{trigger.data.teacherId}}",
          studentId: "{{trigger.data.studentId}}",
        },
      },
    },
  ],
})
```

### Weekly Report via Cron

```typescript
import { defineTrigger } from 'struere'

export default defineTrigger({
  name: "Weekly Report",
  slug: "weekly-report",
  on: {
    schedule: "0 9 * * 1",
    timezone: "America/New_York",
  },
  actions: [
    {
      tool: "agent.chat",
      args: {
        agent: "reporting",
        message: "Generate and send the weekly summary report",
      },
    },
  ],
})
```

---

## defineRouter

> Define routing rules to direct conversations to the right agent

Source: https://docs.struere.dev/sdk/define-router.md

The `defineRouter` function creates routing rules that direct conversations to the right agent on a shared channel. Each router is defined in its own file under the `routers/` directory.

```typescript
import { defineRouter } from 'struere'

export default defineRouter({
  name: "Support Router",
  slug: "support-router",
  description: "Routes incoming WhatsApp messages to the right team",
  mode: "rules",
  agents: [
    { slug: "sales-agent", description: "Handles new leads and pricing questions" },
    { slug: "support-agent", description: "Handles technical issues and bug reports" },
  ],
  rules: [
    {
      conditions: [
        { field: "contact.type", operator: "eq", value: "lead" },
      ],
      route: "sales-agent",
    },
    {
      conditions: [
        { field: "contact.type", operator: "eq", value: "customer" },
      ],
      route: "support-agent",
    },
  ],
  fallback: "support-agent",
})
```

## RouterConfig

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Display name for the router |
| `slug` | `string` | Yes | Unique identifier for the router |
| `description` | `string` | No | Human-readable description of the routing logic |
| `mode` | `'rules' \| 'classify'` | Yes | Routing strategy: condition-based or LLM classification |
| `agents` | `RouterAgentRef[]` | Yes | List of agents this router can route to (at least one required) |
| `rules` | `RouterRule[]` | When mode is `rules` | Ordered list of routing rules evaluated top-to-bottom |
| `fallback` | `string` | Yes | Agent slug to use when no rule matches or classification is uncertain |
| `classifyModel` | `{ model: string; temperature?: number; maxTokens?: number }` | When mode is `classify` | Model config in OpenRouter format for intent classification |
| `contextMessages` | `number` | No | Number of recent messages to include for classification context (default: 5) |
| `maxTransfers` | `number` | No | Maximum number of agent-to-agent transfers per conversation (default: 5) |
| `inactivityResetMs` | `number` | No | Milliseconds of inactivity before `currentAgentId` clears (default: 4 hours) |
| `voiceConfig` | `VoiceConfig` | No | Voice call settings. Voice configuration lives on a router; phones bound directly to an agent use platform defaults. See [Voice integration](/integrations/voice). |

### Validation

`defineRouter` throws errors if:

- `name` is missing
- `slug` is missing
- `agents` is missing or empty
- `fallback` does not reference a slug in `agents`
- `mode` is `rules` and `rules` is empty or missing
- Any rule has an empty `conditions` array
- Any rule's `route` does not reference a slug in `agents`
- Any condition is missing a `field`
- Any condition has an invalid `operator` (must be one of: `eq`, `neq`, `in`, `contains`, `regex`, `gt`, `lt`, `exists`)

### router.transfer

When a thread is created via a router, the `router.transfer` tool is automatically injected into each agent's tool list. Agents can call `router.transfer` to hand off the conversation to another agent within the same router.

```typescript
router.transfer({
  targetAgentSlug: "billing-agent",
  reason: "Customer is asking about their invoice"
})
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `targetAgentSlug` | `string` | Yes | Slug of the agent to transfer to (must be in the router's `agents` list) |
| `reason` | `string` | No | Explanation of why the transfer is happening |

Calling `router.transfer` on a thread that was not created via a router throws an error.

## RouterAgentRef

Each agent reference identifies an agent the router can route to.

```typescript
interface RouterAgentRef {
  slug: string
  description: string
}
```

| Field | Type | Description |
|-------|------|-------------|
| `slug` | `string` | Slug of the agent to route to |
| `description` | `string` | Description used by LLM classification to understand what this agent handles |

## RouterRule

Each rule defines a set of conditions and a target agent.

```typescript
interface RouterRule {
  conditions: RouterRuleCondition[]
  route: string
}
```

| Field | Type | Description |
|-------|------|-------------|
| `conditions` | `RouterRuleCondition[]` | All conditions must match for the rule to activate (AND logic) |
| `route` | `string` | Slug of the agent to route to when all conditions match |

Rules are evaluated top-to-bottom. The first matching rule wins. If no rule matches, the `fallback` agent handles the conversation.

## RouterRuleCondition

Each condition evaluates a field against a value using an operator.

```typescript
interface RouterRuleCondition {
  field: string
  operator: string
  value: unknown
}
```

| Field | Type | Description |
|-------|------|-------------|
| `field` | `string` | The field to evaluate (see available fields below) |
| `operator` | `string` | Comparison operator |
| `value` | `unknown` | Value to compare against |

### Available Fields

| Field | Type | Description |
|-------|------|-------------|
| `phoneNumber` | `string` | Sender's phone number |
| `channel` | `string` | Message channel (e.g., `whatsapp`, `api`) |
| `{entityType}.*` | `any` | Any field from an entity matched by phone number. The prefix is the entity type slug — `teacher.name` queries the `teacher` entity type, `contact.tier` queries `contact`, `student.grade` queries `student`. The routing engine extracts the entity type from the prefix and looks up the entity by the sender's phone number. |
| `time.hour` | `number` | Current hour (0-23) in the organization's timezone |
| `time.dayOfWeek` | `number` | Current day of week (0 = Sunday, 6 = Saturday) |
| `message.text` | `string` | Text content of the incoming message |
| `message.type` | `string` | Message type (e.g., `text`, `image`, `audio`) |

### Available Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equal to | `{ field: "channel", operator: "eq", value: "whatsapp" }` |
| `neq` | Not equal to | `{ field: "message.type", operator: "neq", value: "text" }` |
| `in` | Value is in array | `{ field: "customer.plan", operator: "in", value: ["pro", "enterprise"] }` |
| `contains` | String contains substring | `{ field: "message.text", operator: "contains", value: "pricing" }` |
| `regex` | Matches regular expression | `{ field: "phoneNumber", operator: "regex", value: "^\\+44" }` |
| `gt` | Greater than | `{ field: "time.hour", operator: "gt", value: 17 }` |
| `lt` | Less than | `{ field: "time.hour", operator: "lt", value: 9 }` |
| `exists` | Field exists and is not null | `{ field: "customer.assignedAgent", operator: "exists", value: true }` |

## Routing Modes

### Rules Mode

Rules mode evaluates conditions with zero LLM cost. Each rule is checked top-to-bottom until a match is found:

```typescript
export default defineRouter({
  name: "Hours Router",
  slug: "hours-router",
  mode: "rules",
  agents: [
    { slug: "live-agent", description: "Live support during business hours" },
    { slug: "after-hours-agent", description: "Automated support outside business hours" },
  ],
  rules: [
    {
      conditions: [
        { field: "time.hour", operator: "gt", value: 8 },
        { field: "time.hour", operator: "lt", value: 18 },
        { field: "time.dayOfWeek", operator: "gt", value: 0 },
        { field: "time.dayOfWeek", operator: "lt", value: 6 },
      ],
      route: "live-agent",
    },
  ],
  fallback: "after-hours-agent",
})
```

Multiple conditions within a rule use AND logic. The first matching rule wins.

### Classify Mode

Classify mode uses an LLM to determine intent from the conversation context. The LLM receives the agent descriptions and recent messages, then selects the best agent:

```typescript
export default defineRouter({
  name: "Intent Router",
  slug: "intent-router",
  mode: "classify",
  agents: [
    { slug: "billing-agent", description: "Handles invoices, payments, refunds, and subscription changes" },
    { slug: "technical-agent", description: "Handles bug reports, API questions, and technical troubleshooting" },
    { slug: "onboarding-agent", description: "Handles account setup, getting started, and feature walkthroughs" },
  ],
  classifyModel: { model: "openai/gpt-5-mini" },
  contextMessages: 5,
  fallback: "technical-agent",
})
```

The `description` field on each `RouterAgentRef` is critical in classify mode — it provides the LLM with the context to make accurate routing decisions.

## VoiceConfig

When a router is assigned to a Twilio phone number via `voiceConnections`, voice calls use the router's `voiceConfig` to configure the OpenAI Realtime session.

```typescript
interface VoiceConfig {
  provider: string
  model?: string
  voice: string
  auditorAgent?: string
  pollInterval?: number
  turnDetection?: ServerVadConfig | SemanticVadConfig
  noiseReduction?: "near_field" | "far_field"
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `provider` | `string` | `"openai-realtime"` | Voice provider (only `"openai-realtime"` currently) |
| `model` | `string` | `"gpt-realtime-mini"` | OpenAI Realtime model: `"gpt-realtime-mini"` or `"gpt-realtime-1.5"` |
| `voice` | `string` | `"alloy"` | Voice: `alloy`, `ash`, `ballad`, `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, `cedar` |
| `auditorAgent` | `string` | -- | Slug of auditor agent for dual-agent mode |
| `pollInterval` | `number` | `5000` | Auditor polling interval in ms |
| `turnDetection` | `object` | `semantic_vad` | Turn detection config (see below) |
| `noiseReduction` | `string` | -- | `"near_field"` (close mic) or `"far_field"` (speakerphone) |

**Turn detection options:**

```typescript
{ type: "semantic_vad", eagerness?: "low" | "medium" | "high" | "auto" }
{ type: "server_vad", threshold?: number, silenceDurationMs?: number, prefixPaddingMs?: number }
```

**Example:**

```typescript
import { defineRouter } from 'struere'

export default defineRouter({
  name: "Voice Intake",
  slug: "voice-intake",
  mode: "classify",
  agents: [
    { slug: "intake-agent", description: "Collects caller information" },
    { slug: "support-agent", description: "Handles support requests" },
  ],
  classifyModel: { model: "openai/gpt-5-mini" },
  fallback: "intake-agent",
  voiceConfig: {
    provider: "openai-realtime",
    model: "gpt-realtime-mini",
    voice: "coral",
    auditorAgent: "form-auditor",
    pollInterval: 5000,
    turnDetection: { type: "semantic_vad", eagerness: "medium" },
    noiseReduction: "near_field",
  },
})
```

## Full Examples

### Route by Phone Number

Route internal team messages to a different agent than customer messages:

```typescript
import { defineRouter } from 'struere'

export default defineRouter({
  name: "Team Router",
  slug: "team-router",
  mode: "rules",
  agents: [
    { slug: "internal-agent", description: "Internal team assistant" },
    { slug: "customer-agent", description: "Customer-facing support agent" },
  ],
  rules: [
    {
      conditions: [
        { field: "phoneNumber", operator: "regex", value: "^\\+1555" },
      ],
      route: "internal-agent",
    },
  ],
  fallback: "customer-agent",
})
```

### Route by Contact Type

Route based on data stored on the contact entity:

```typescript
import { defineRouter } from 'struere'

export default defineRouter({
  name: "Contact Router",
  slug: "contact-router",
  mode: "rules",
  agents: [
    { slug: "vip-agent", description: "Dedicated support for enterprise customers" },
    { slug: "sales-agent", description: "Handles leads and trials" },
    { slug: "general-agent", description: "General support for all customers" },
  ],
  rules: [
    {
      conditions: [
        { field: "contact.plan", operator: "in", value: ["enterprise"] },
      ],
      route: "vip-agent",
    },
    {
      conditions: [
        { field: "contact.type", operator: "eq", value: "lead" },
      ],
      route: "sales-agent",
    },
  ],
  fallback: "general-agent",
})
```

### LLM Classification with Transfer Cap

```typescript
import { defineRouter } from 'struere'

export default defineRouter({
  name: "Smart Router",
  slug: "smart-router",
  mode: "classify",
  agents: [
    { slug: "billing-agent", description: "Invoices, payments, refunds, and plan changes" },
    { slug: "support-agent", description: "Technical issues, bugs, and how-to questions" },
    { slug: "sales-agent", description: "Pricing, demos, and new feature inquiries" },
  ],
  classifyModel: { model: "anthropic/claude-sonnet-4" },
  contextMessages: 3,
  maxTransfers: 3,
  inactivityResetMs: 1800000,
  fallback: "support-agent",
})
```

---

## defineTools

> Create custom tool handlers for agents

Source: https://docs.struere.dev/sdk/define-tools.md

The `defineTools` function creates and validates custom tool handlers. Custom tools are defined in `tools/index.ts` and synced to the platform as standalone org-level resources in the `customTools` table. Agents reference tools by name in their `tools` array — tools do not need to be embedded in agent definitions.

```typescript
import { defineTools } from 'struere'

export default defineTools([
  {
    name: "send_email",
    description: "Send an email to a recipient",
    parameters: {
      type: "object",
      properties: {
        to: { type: "string", description: "Recipient email address" },
        subject: { type: "string", description: "Email subject line" },
        body: { type: "string", description: "Email body content" },
      },
      required: ["to", "subject", "body"],
    },
    handler: async (args, context, struere, fetch) => {
      const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${process.env.SENDGRID_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          personalizations: [{ to: [{ email: args.to }] }],
          from: { email: "noreply@example.com" },
          subject: args.subject,
          content: [{ type: "text/plain", value: args.body }],
        }),
      })
      return { success: response.ok }
    },
  },
])
```

## Tool Definition

Each tool in the array requires the following fields:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Unique tool identifier, referenced in agent `tools` arrays |
| `description` | `string` | Yes | Description shown to the LLM for tool selection |
| `parameters` | `ToolParameters` | Yes | JSON Schema defining the tool's input parameters |
| `handler` | `function` | Yes | Async function that executes when the tool is called |
| `templateOnly` | `boolean` | No | If true, tool is only available during system prompt template compilation and not exposed to the LLM at runtime. Defaults to `false`. |

### Validation

`defineTools` throws errors if any tool is missing `name`, `description`, `parameters`, or `handler`.

## Handler Function

The handler function receives four arguments:

```typescript
handler: async (args, context, struere, fetch) => {
  return { result: "value" }
}
```

| Argument | Type | Description |
|----------|------|-------------|
| `args` | `Record<string, unknown>` | Parsed arguments matching the `parameters` schema |
| `context` | `ToolContext` | Actor and organization context |
| `struere` | `StruereSDK` | SDK object providing access to all built-in tools |
| `fetch` | `function` | Native fetch function for making HTTP requests to any domain |

The handler must return a JSON-serializable value. This value is passed back to the LLM as the tool result.

### ToolContext

```typescript
interface ToolContext {
  organizationId?: string
  actorId?: string
  actorType?: string
  conversationId?: string
  userId?: string
}
```

| Field | Description |
|-------|-------------|
| `organizationId` | The Convex organization ID of the caller |
| `actorId` | The ID of the user or agent making the call |
| `actorType` | Whether the caller is a `"user"`, `"agent"`, or `"system"` |
| `conversationId` | The ID of the current conversation thread |
| `userId` | The ID of the end user in the conversation |

### StruereSDK

The `struere` parameter gives custom tool handlers access to all built-in tools. This enables custom tools to compose platform operations without making raw API calls.

```typescript
import type { StruereSDK } from 'struere'
```

Available namespaces:

| Namespace | Methods |
|-----------|---------|
| `struere.entity` | `create`, `get`, `query`, `update`, `delete` |
| `struere.event` | `emit`, `query` (**deprecated** — return `{ deprecated: true }`) |
| `struere.whatsapp` | `send`, `sendTemplate`, `sendInteractive`, `sendMedia`, `listTemplates`, `getConversation`, `getStatus` |
| `struere.calendar` | `list`, `create`, `update`, `delete`, `freeBusy` |
| `struere.airtable` | `listBases`, `listTables`, `listRecords`, `getRecord`, `createRecords`, `updateRecords`, `deleteRecords` |
| `struere.email` | `send` |
| `struere.payment` | `create`, `getStatus` |
| `struere.agent` | `chat` |
| `struere.web` | `search`, `fetch` |

Example using `struere` to create an entity inside a custom tool handler:

```typescript
export default defineTools([
  {
    name: "onboard_student",
    description: "Register a new student and emit an onboarding event",
    parameters: {
      type: "object",
      properties: {
        name: { type: "string" },
        email: { type: "string" },
      },
      required: ["name", "email"],
    },
    handler: async (args, context, struere) => {
      const student = await struere.entity.create({
        type: "student",
        data: { name: args.name, email: args.email },
      })
      await struere.event.emit({
        eventType: "student.onboarded",
        entityId: student.id,
      })
      return { studentId: student.id }
    },
  },
])
```

## Using Custom Tools in Agents

Reference custom tools by their `name` in any agent's `tools` array:

```typescript
import { defineAgent } from 'struere'

export default defineAgent({
  name: "Support Agent",
  slug: "support",
  version: "1.0.0",
  systemPrompt: "You are a customer support agent.",
  tools: [
    "entity.query",
    "entity.update",
    "event.emit",
    "send_email",
  ],
})
```

### Template-Only Tools

Tools defined with `templateOnly: true` are executed during system prompt template compilation but are not exposed to the LLM as callable tools at runtime. This lets you inject dynamic data into system prompts without bloating the agent's tool list.

Template-only tools are available to **all agents** in the organization automatically. They do not need to be listed in any agent's `tools` array to be used in system prompt templates.

```typescript
export default defineTools([
  {
    name: 'format_teacher_schedule',
    description: 'Query teachers and format availability into a readable schedule',
    templateOnly: true,
    parameters: {
      type: 'object',
      properties: {},
    },
    handler: async (args, context, struere) => {
      const result = await struere.entity.query({ type: 'teacher' })
      const teachers = Array.isArray(result) ? result : result?.results || []
      return teachers.map((t) => `${t.data?.name}: ${JSON.stringify(t.data?.availability)}`).join('\n')
    },
  },
])
```

Reference the tool in any agent's system prompt using template syntax:

```
{{format_teacher_schedule()}}
```

Template-only tools don't count toward the agent's runtime tool list.

Custom tool names and built-in tool names share the same namespace. Avoid naming conflicts by not using the `entity.`, `event.`, or `agent.` prefixes for custom tools.

For execution environment details and more examples, see [Custom Tools](../tools/custom-tools).