# Dynamic Behaviors

Schema reference for the tables that hold dynamic behavior configurations, their trigger definitions, and the record of each invocation at runtime.

## CLI Management

Dynamic behaviors are first-class assets in Agent Forge (v0.2.25+), which means you can discover and manage them end to end from the CLI.

### Discovery Commands

```bash
# List all dynamic behaviors
forge asset behavior list -e production

# View version history for a behavior
forge asset behavior version-list "Emergency Response Protocol" -e production

# Show detailed behavior version info
forge asset behavior version-show "Emergency Response Protocol" 3 -e production
```

### Invocation History

Check when and where a behavior was triggered across conversations:

```bash
# List recent invocations by name
forge asset behavior invocations "Emergency Response Protocol" -e production

# Limit results
forge asset behavior invocations "Emergency Response Protocol" -e production -n 10

# JSON output (includes conversation_id, service_id, user_id, version info)
forge asset behavior invocations "Emergency Response Protocol" -e production --json
```

Output shows the `invoked_at` timestamp, conversation ID, service ID, user ID, and behavior version for each trigger event. It's useful for verifying triggers fire correctly and for auditing activation frequency.

### Service Integration

```bash
# View services with applied behaviors
forge service show MyService -e production
# Output includes:
#   Dynamic Behaviors: 3 applied
#     - Emergency Response Protocol (id123) ✓
#     - Calorie Target Guidance (id456) ✓
#     - Safety Screening (id789) ✗

# View behaviors in version sets
forge version-set show release -s MyService -e production
# Shows: Applied Behaviors: [behavior1, behavior2, ...]
```

### Version Management

Dynamic behaviors can be versioned alongside deployments.

```bash
# Apply behaviors to a version set
forge version-set upsert preview -s MyService -e production \
  --behaviors "id123,id456,id789" --apply
```

### Dynamic Behavior Sets Table

**Table Name:** `dynamic_behavior_sets`\
**Description:** Dynamic behavior configurations for services

{% tabs %}
{% tab title="Schema" %}

| Column                    | Type           | Description                   |
| ------------------------- | -------------- | ----------------------------- |
| `_id`                     | string         | Behavior set identifier       |
| `applied_to_services`     | array\<string> | Associated service IDs        |
| `created_at`              | timestamp      | Creation timestamp            |
| `creator_user_id`         | string         | Creator user ID               |
| `is_active`               | boolean        | Active status                 |
| `is_deleted`              | boolean        | Deletion status               |
| `latest_version_triggers` | json           | Current trigger configuration |
| `name`                    | string         | Behavior set name             |
| `org_id`                  | string         | Organization identifier       |
| `region_name`             | string         | Deployment region             |
| `tags`                    | json           | Associated tags               |
| `updated_at`              | timestamp      | Last update timestamp         |
| `updated_by_user_id`      | string         | Last updater user ID          |
| {% endtab %}              |                |                               |

{% tab title="Query Example" %}

```sql
SELECT
  _id,
  name,
  applied_to_services,
  is_active,
  updated_at
FROM dynamic_behavior_sets
WHERE is_active = true
  AND is_deleted = false;
```

{% endtab %}
{% endtabs %}

### Dynamic Behavior Triggers Table

**Table Name:** `dynamic_behavior_triggers`\
**Description:** Trigger definitions for dynamic behaviors

{% tabs %}
{% tab title="Schema" %}

| Column                           | Type           | Description              |
| -------------------------------- | -------------- | ------------------------ |
| `_id`                            | string         | Trigger identifier       |
| `conversation_trigger`           | string         | Trigger condition        |
| `conversation_trigger_embedding` | array\<number> | Trigger embedding vector |
| `created_at`                     | timestamp      | Creation timestamp       |
| `dynamic_behavior_set_id`        | string         | Parent behavior set ID   |
| `dynamic_behavior_set_version`   | integer        | Behavior set version     |
| `expired_at`                     | timestamp      | Expiration timestamp     |
| `org_id`                         | string         | Organization identifier  |
| `region_name`                    | string         | Deployment region        |
| `updated_at`                     | timestamp      | Last update timestamp    |
| {% endtab %}                     |                |                          |

{% tab title="Query Example" %}

```sql
SELECT
  conversation_trigger,
  dynamic_behavior_set_id,
  dynamic_behavior_set_version,
  expired_at
FROM dynamic_behavior_triggers
WHERE expired_at IS NULL OR expired_at > NOW();
```

{% endtab %}
{% endtabs %}

### Dynamic Behavior Invocations Table

**Table Name:** `dynamic_behavior_invocations`\
**Description:** Records of triggered dynamic behaviors in conversations

{% tabs %}
{% tab title="Schema" %}

| Column                              | Type           | Description                |
| ----------------------------------- | -------------- | -------------------------- |
| `_id`                               | string         | Invocation identifier      |
| `agent_inner_thoughts_ids`          | array\<string> | Agent thought IDs          |
| `agent_message_id`                  | string         | Agent message ID           |
| `conversation_id`                   | string         | Associated conversation ID |
| `created_at`                        | timestamp      | Creation timestamp         |
| `dynamic_behavior_set_version_info` | json           | Version information        |
| `external_event_message_ids`        | array\<string> | External event IDs         |
| `initial_message_id`                | string         | Initial message ID         |
| `invoked_at`                        | timestamp      | Invocation timestamp       |
| `org_id`                            | string         | Organization identifier    |
| `region_name`                       | string         | Deployment region          |
| `service_id`                        | string         | Associated service ID      |
| `updated_at`                        | timestamp      | Last update timestamp      |
| `user_id`                           | string         | Associated user ID         |
| {% endtab %}                        |                |                            |

{% tab title="Query Example" %}

```sql
SELECT
  conversation_id,
  service_id,
  user_id,
  invoked_at,
  dynamic_behavior_set_version_info
FROM dynamic_behavior_invocations
ORDER BY invoked_at DESC;
```

{% endtab %}
{% endtabs %}