Events

NDJSON event types for conversation streams: messages, actions, errors, and audio fillers.

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	The first event on Interact streams. Contains the full text of the user message (user_message) and its message_id; for voice messages it carries the completed transcription.
NewMessageEvent	new-message	Streaming message chunks from the agent (text or voice).
InteractionCompleteEvent	interaction-complete	Indicates the current interaction completed successfully and was committed to the database.
ErrorEvent	error	Indicates an error during the stream. Received before interaction-complete: the interaction is void; retry it. Received after: the interaction is saved, but post-processing failed; call the Finish endpoint to retry it.
CurrentAgentActionEvent	current-agent-action	Emitted by default for all agent action types (requires the Conversation:GetInteractionInsights permission). The current_agent_action_type query parameter is a regex filter defaulting to ^.*$ (match all); set it to a regex that matches nothing, such as ^$, to suppress these events.
ActionTooLongEvent	action-too-long	Not a top-level event. Delivered as the action payload of a current-agent-action event (type = current-agent-action, action.type = 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. If one arrives before interaction-complete, nothing from that interaction is persisted; if it arrives after, the interaction is persisted and only the post-processing failed.

Understanding Agent Actions

CurrentAgentActionEvent reveals agent behavior during generation.

Dynamic Behavior Selection Completed

Emitted when the agent completes dynamic behavior selection. selected_dynamic_behavior_set_version_info identifies the selected dynamic behavior set version (or null if none was selected), and previous_selected_dynamic_behavior_set_version_info identifies the previously selected version (or null).

{
  "type": "current-agent-action",
  "action": {
    "type": "select-dynamic-behavior-completed",
    "selected_dynamic_behavior_set_version_info": ["<DYNAMIC-BEHAVIOR-SET-ID>", 3],
    "previous_selected_dynamic_behavior_set_version_info": null
  }
}

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

System Integration Flow

1. Capture selected_dynamic_behavior_set_version_info when the event appears.

2. Map behavior IDs to the metrics you want to compute in your system.

3. 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

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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

versionstring · nullableOptional

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

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-namestring · nullableOptional

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.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded.

application/json

has_morebooleanRequired

Whether there are more dynamic behavior set versions to retrieve.

continuation_tokeninteger · nullableRequired

A token to supply to the next request to retrieve the next page of dynamic behavior set versions. Only populated if has_more is True.

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": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "dynamic_behavior_set_id": "text",
      "version": 1,
      "conversation_triggers": [
        "text"
      ],
      "actions": [
        {
          "type": "text",
          "instruction": "text",
          "overrides_instructions": true
        }
      ],
      "creator": {
        "org_id": "text",
        "user_id": "text"
      }
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Compute Metrics

Evaluate metrics

post

/v1/{organization}/metric/evaluate

Evaluate the latest versions of specified metrics for a completed conversation. The results will be stored and retrievable through the GetMetricEvaluationResults endpoint with a special source type of manual.

If the same conversation has been manually evaluated for the same metric, the previous evaluation result will be overwritten.

Permissions

This endpoint requires the following permissions:

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

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

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

Header parameters

x-mongo-cluster-namestring · nullableOptional

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.

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_idstring · nullableOptional

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

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

Responses

200

Succeeded.

application/json

400

The conversation has no interactions.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, conversation, or metric is not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 50 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",
      "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_round_index": 0,
      "tool_id": "<TOOL-ID>",
      "tool_version": "1.0.0",
      "input_params": { "query": "warranty coverage" }
    }
  }
}

previously_started_event echoes whichever in-progress action event exceeded its threshold. It is not limited to tool-call-started - it can also be other in-progress action events, such as decision, reflection, or parameter-generation events.

Purpose

Audio fillers improve voice conversation experiences by:

• Reducing perceived latency: they play contextual audio during processing delays.

• Maintaining conversation flow: they provide natural feedback instead of silence.

• Improving user experience: 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.

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..."

Audio filler configuration by Context Graph state type

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 chosen at random and played.

Best Practice: Keep Delays Close to Zero

The audio_filler_triggered_after value should be as close to zero as possible (e.g., 0.0001). Any delay adds directly to perceived latency for users. Since most operations complete quickly, adding delays hurts the majority of interactions.

Recommended: "audio_filler_triggered_after": 0.0001

The schema requires > 0, so you cannot use exactly 0, but values below 1ms (0.001s) are instantaneous in practice. Agent Forge will warn if your delay is ≥ 1ms.

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 chosen at random 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

1. Keep fillers natural: use conversational phrases appropriate for your use case.

2. Match the context: different states can have different fillers (for example, "Searching..." for search tools).

3. Set appropriate timeouts: balance between too frequent (annoying) and too late (awkward silence).

4. Provide variety: configure multiple fillers to avoid repetition in longer conversations.