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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/data-access/organization-tables/dynamic-behaviors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.