Events

When creating or interacting with conversations, the API responds with an NDJSON stream of events. This page summarizes the event types and how to use them.

Event Types

Event

type

Description

ConversationCreatedEvent

conversation-created

Contains the conversation_id for subsequent calls.

UserMessageAvailableEvent

user-message-available

Present when initial_message is provided; may represent a user message or an external event.

NewMessageEvent

new-message

Streaming message chunks from the agent (text or voice).

InteractionCompleteEvent

interaction-complete

Indicates the current interaction completed successfully.

ErrorEvent

error

Indicates an internal error; the interaction is rolled back.

CurrentAgentActionEvent

current-agent-action

Emitted only when the current_agent_action_type query parameter is set.

ActionTooLongEvent

action-too-long

Indicates an agent action is taking longer than expected; provides audio/text filler for voice mode.

Important Notes

Persist conversation_id from conversation-created.
Continue reading until interaction-complete.
Handle error events; nothing from that interaction is persisted.

Understanding Agent Actions

CurrentAgentActionEvent reveals agent behavior during generation.

Dynamic Behavior Triggered

Emitted when a dynamic behavior is triggered.

{
  "type": "current-agent-action",
  "action": {
    "type": "dynamic-behavior-triggered",
    "dynamic_behavior_set_version_info": ["<DYNAMIC-BEHAVIOR-SET-ID>", 3]
  }
}

Use this as a trigger to evaluate metrics and drive business workflows.

System Integration Flow

Capture dynamic_behavior_set_version_info when the event appears.
Map behavior IDs to the metrics you want to compute in your system.
Evaluate metrics and act (route, escalate, create tickets, store results).

Retrieve Dynamic Behavior Set Versions

Get dynamic behavior set versions

get

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/

Get the versions of a dynamic behavior set.

Permissions

This endpoint requires the following permissions:

DynamicBehaviorInstruction:GetDynamicBehaviorInstruction for the dynamic behavior set to retrieve.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

dynamic_behavior_set_idstringRequired

The ID of the dynamic behavior set.

Pattern: ^[a-f0-9]{24}$

Query parameters

versionany ofOptional

The versions of the dynamic behavior set to retrieve. One can specify an exact version to retrieve, which is either the version number or latest, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -, and every version within the range would be retrieved.

Example: 1

stringOptional

nullOptional

limitinteger · max: 10Optional

The maximum number of dynamic behavior set versions to return.

Default: 10

continuation_tokenintegerOptional

The continuation token from the previous request used to retrieve the next page of dynamic behavior set versions.

Default: 0

sort_bystring[]Optional

The fields to sort the versions by. Supported fields are version. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or dynamic behavior set is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 1000 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/

GET /v1/{organization}/dynamic_behavior_set/{dynamic_behavior_set_id}/version/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "dynamic_behavior_set_versions": [
    {
      "_id": "text",
      "org_id": "text",
      "created_at": "2025-12-03T05:34:27.958Z",
      "updated_at": "2025-12-03T05:34:27.958Z",
      "dynamic_behavior_set_id": "text",
      "version": 1,
      "conversation_triggers": [
        "text"
      ],
      "action": {
        "type": "text",
        "instruction": "text",
        "overrides_instructions": true
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Compute Metrics

Evaluate metrics

post

/v1/{organization}/metric/evaluate

Evaluate the specified metrics for the given conversation, optionally up to the specified interaction.

Permissions

This endpoint requires the following permissions:

Metric:EvaluateMetric for the metrics.
Metric:GetMetricEvaluationResult for the metric results.

Authorizations

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

metric_idsstring[] · min: 1 · max: 10Required

The IDs of the metrics to evaluate.

conversation_idstringRequired

The ID of the conversation to evaluate the metrics for.

Pattern: ^[a-f0-9]{24}$

evaluate_to_interaction_idany ofOptional

If specified, only messages up to (and including) this interaction will be evaluated.

stringOptionalPattern: ^[a-f0-9]{24}$

nullOptional

Responses

200

Succeeded.

application/json

400

The conversation has no interactions.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, conversation, interaction, or metric is not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/metric/evaluate

POST /v1/{organization}/metric/evaluate HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "metric_ids": [
    "text"
  ],
  "conversation_id": "text",
  "evaluate_to_interaction_id": "text"
}

{
  "metrics": [
    {
      "metric_id": "text",
      "name": "text",
      "value": 1,
      "references": [
        "text"
      ],
      "justification": "text"
    }
  ]
}

curl --request POST \
  --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/metric/evaluate' \
  --header 'Authorization: Bearer <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "metric_ids": ["metric_id_1", "metric_id_2"],
    "conversation_id": "<CONVERSATION-ID>",
    "evaluate_to_interaction_id": "<INTERACTION-ID>"
  }'

Managing Perceived Latency with Audio Fillers

When using response_format=voice, the agent may emit ActionTooLongEvent during interactions where operations exceed configured time thresholds.

{
  "type": "current-agent-action",
  "action": {
    "type": "action-too-long",
    "filler": "base64_encoded_audio_or_text",
    "previously_started_event": {
      "type": "tool-call-started",
      "tool_name": "search_knowledge_base"
    }
  }
}

Purpose

Audio fillers enhance voice conversation experiences by:

Reducing perceived latency - Playing contextual audio during processing delays
Maintaining conversation flow - Providing natural feedback instead of silence
Improving user experience - Making wait times feel shorter and more natural

Event Structure

Field

Type

Description

type

"action-too-long"

Event type identifier

filler

string

Base64-encoded PCM audio (16kHz, 16-bit, mono) or plain text

previously_started_event

object

The action that is taking longer than expected

Audio Filler Types

Audio fillers are triggered in different scenarios based on Context Graph state types. Context Graphs define how agents navigate problem spaces using different types of states:

Context Graph State Types

Context Graphs (API: service_hierarchical_state_machine) consist of different state types:

ActionState - Perform actions toward an objective
DecisionState - Choose between multiple paths
ReflectionState - Generate internal analysis
ToolCallState - Execute a specific tool end-to-end
RecallState, AnnotationState - (no audio fillers)

Learn more about Context Graphs in our Conceptual Documentation.

Audio fillers are triggered in these scenarios:

1. Decision-Making Delays (DecisionState) When the agent's decision-making LLM interaction exceeds the timeout:

Examples: "Let me think about that...", "Just a moment..."

2. Reflection Delays (ReflectionState) When reflection generation exceeds the timeout:

Examples: "Let me consider this carefully...", "Analyzing that information..."

3. Designated Tool Delays (ToolCallState) When the entire tool call process (parameter generation + execution) exceeds the timeout:

Examples: "I'm looking that up for you...", "Searching now...", "Let me check on that..."

4. Helper Tool Delays (during param generation, decisions, reflections, actions) When helper tools executed during other operations exceed their timeouts:

Examples: "Checking that information...", "One moment...", "Let me verify..."

Configuration

Audio fillers are configured in the service's Context Graph (API field: service_hierarchical_state_machine) using state-specific fields. Each state type in a Context Graph can have audio fillers configured:

DecisionState:

audio_fillers + audio_filler_triggered_after - For the decision-making process
tool_call_specs[].audio_fillers + audio_filler_triggered_after - For helper tools during decision

ReflectionState:

audio_fillers + audio_filler_triggered_after - For the reflection generation
tool_call_specs[].audio_fillers + audio_filler_triggered_after - For helper tools during reflection

ToolCallState:

designated_tool_call_params_generation_audio_fillers + designated_tool_call_params_generation_audio_filler_triggered_after - For the entire designated tool process (param generation + execution)
tool_call_specs[].audio_fillers + audio_filler_triggered_after - For helper tools during param generation

ActionState:

action_tool_call_specs[].audio_fillers + audio_filler_triggered_after - For tools used during actions
exit_condition_tool_call_specs[].audio_fillers + audio_filler_triggered_after - For tools used when evaluating exit conditions

All audio_fillers are arrays of text strings (max 5). All audio_filler_triggered_after are timeouts in seconds (0 < x ≤ 10). When an operation exceeds its threshold, one audio filler is randomly selected and played.

Related: Tool Result Persistence

Tool call specifications (tool_call_specs, action_tool_call_specs, exit_condition_tool_call_specs) also include a result_persistence property that controls how tool outputs are stored and made available to the agent across interactions. See Tools: Result Persistence for configuration details.

Implementation Notes

Pre-generation: Audio fillers are pre-generated using the agent's voice configuration when a conversation starts
Storage: Generated audio is stored as base64-encoded PCM WAV (16kHz, 16-bit, mono)
Selection: One filler is randomly chosen when the threshold is exceeded
Transparency: The filler field contains either the generated audio (base64) or the original text if audio generation failed

Best Practices

Keep fillers natural: Use conversational phrases appropriate for your use case
Match the context: Different states can have different fillers (e.g., "Searching..." for search tools)
Set appropriate timeouts: Balance between too frequent (annoying) and too late (awkward silence)
Provide variety: Configure multiple fillers to avoid repetition in longer conversations

PreviousInteract NextLifecycle & Finish

Last updated 19 days ago

Was this helpful?

Good night

Event Types

Important Notes

Understanding Agent Actions

Dynamic Behavior Triggered

System Integration Flow

Retrieve Dynamic Behavior Set Versions

Get dynamic behavior set versions

Permissions

Compute Metrics

Evaluate metrics

Permissions

Managing Perceived Latency with Audio Fillers

Purpose

Event Structure

Audio Filler Types

Configuration

Implementation Notes

Best Practices