Observe and govern
Concept Available

Activity, Conversations, and Runtime Telemetry

Provider messages enter through the Communications Gateway, which persists canonical inbound and outbound Conversation Messages scoped to a Communication Connection. Ingest accepts only Runtime Tool Call telemetry, and both surface in Agent Activity through authorized Product API reads.

For
Agent operators and developers
On this page
  1. Who writes what
  2. Data flow
  3. Conversation ingestion
  4. Reply binding
  5. Conversation identity
  6. Name enrichment
  7. Conversation read routes
  8. Runtime telemetry ingestion
  9. Tool Call reads
  10. Authentication boundaries
  11. What Activity is not
  12. Activity in the web app
  13. Where to look next
01

Who writes what

Conversations and Tool Calls appear together in Agent Activity, but they are written by different services through separate pipelines.

  1. 01.1

    Ingest does not own or receive Conversation Messages. The Runtime Communications protocol and Ingest telemetry authentication are separate boundaries with separate credentials.

  2. 01.2

    Provider messages enter through the Communications Gateway.

  3. 01.3

    Platform Plugins normalize and evaluate provider events.

  4. 01.4

    Communications persists canonical inbound and outbound Conversation Messages.

  5. 01.5

    Agent Runtimes use a versioned Communications protocol to claim inbound Deliveries and submit replies.

  6. 01.6

    Ingest accepts only Tool Call and Tool Result telemetry from Agent Runtimes.

  7. 01.7

    Product API routes expose Conversations and Tool Calls to authorized users.

  8. 01.8

    The Agent Activity UI presents these records together while preserving their separate ownership.

02

Data flow

Two write paths converge only at the read layer.

  1. 02.1

    Conversation path: Platform provider

  2. 02.2

    Conversation path: Platform Plugin

  3. 02.3

    Conversation path: Communications Gateway

  4. 02.4

    Conversation path: Communication Deliveries and canonical Conversation Messages

  5. 02.5

    Conversation path: Agent Runtime, exchanging claims and replies over the versioned Communications protocol

  6. 02.6

    Telemetry path: Agent Runtime

  7. 02.7

    Telemetry path: Ingest API

  8. 02.8

    Telemetry path: Tool Call repository

  9. 02.9

    Read path: Conversation reads and Tool Call reads

  10. 02.10

    Read path: Agent Activity UI

03

Conversation ingestion

An inbound provider message becomes a canonical Conversation Message through the Communications path.

  1. 03.1

    A provider message rejected by admission policy may appear in the Communications journal, but it does not become an accepted inbound Delivery or a Conversation Message.

  2. 03.2

    A Platform Plugin receives a provider event.

  3. 03.3

    The plugin authenticates the provider boundary where applicable.

  4. 03.4

    It normalizes the payload into a canonical communication envelope.

  5. 03.5

    Connection-scoped admission policies are evaluated.

  6. 03.6

    Accepted messages create durable inbound Communication Deliveries.

  7. 03.7

    Communications persists the canonical inbound Conversation Message.

  8. 03.8

    The Runtime claims the Delivery through the Communications protocol.

  9. 03.9

    The Runtime submits its reply against the source Delivery.

  10. 03.10

    Communications persists the outbound Conversation Message and delivers it through the originating Platform Plugin.

04

Reply binding

A Runtime reply is bound to its source Communication Delivery, and the Runtime supplies no Platform-routing fields of its own.

  1. 04.1

    The Runtime cannot redirect a reply to another Connection or to an arbitrary provider location. The source Delivery determines:

  2. 04.2

    The owning Agent

  3. 04.3

    The Communication Connection

  4. 04.4

    The Platform

  5. 04.5

    The channel or direct-message location

  6. 04.6

    The thread, where one applies

  7. 04.7

    The outbound destination

05

Conversation identity

A provider message is unique within (connection_id, provider_message_id), so two Connections may legitimately receive the same provider message identifier without colliding.

  1. 05.1

    A Conversation location is identified by (connection_id, channel_id). A channel_id alone is insufficient because an Agent can have multiple Connections, multiple same-Platform Connections can expose identical provider channel IDs, and different providers can use overlapping identifier formats.

  2. 05.2

    Connection identity must therefore remain present in API routes, UI selection, query keys, and persistence filters.

  3. 05.3

    A canonical Conversation Message records:

  4. 05.4

    The openclaw_msg_id column is a legacy internal name now used for provider message identity across all Platforms. It does not indicate OpenClaw-specific behavior.

  5. 05.5

    The Agent ID

  6. 05.6

    The Connection ID

  7. 05.7

    Provider message identity

  8. 05.8

    Direction: INBOUND or OUTBOUND

  9. 05.9

    Conversation type: CHANNEL or DM

  10. 05.10

    Session key

  11. 05.11

    Channel or conversation ID

  12. 05.12

    Optional thread ID

  13. 05.13

    Optional sender ID and display name

  14. 05.14

    Optional channel display name

  15. 05.15

    Message content

  16. 05.16

    Occurrence timestamp

06

Name enrichment

Platform Plugins may perform optional, best-effort name enrichment before canonical message persistence. Communications invokes it centrally, and it applies to supervised ingress, driver events, and provider webhooks.

  1. 06.1

    Enrichment is not an Ingest responsibility.

  2. 06.2

    Provider-supplied sender and location names are preferred.

  3. 06.3

    Missing names may be resolved through credential-scoped provider lookups.

  4. 06.4

    Lookup failure does not delay or reject an otherwise accepted message.

  5. 06.5

    Stable provider IDs remain authoritative.

  6. 06.6

    A duplicate delivery may fill a missing name, but must not erase an existing one.

07

Conversation read routes

Conversation locations are listed through GET /api/v1/organizations/{organization_id}/agents/{agent_id}/conversations/channels.

  1. 07.1

    Messages for one Connection and channel are read through GET /api/v1/organizations/{organization_id}/agents/{agent_id}/conversations/connections/{connection_id}/channels/{channel_id}/messages. No current route identifies a Conversation using only agent_id and channel_id.

  2. 07.2

    Message reads group results into roots and replies, support date filtering, use cursor pagination, and preserve the selected Connection and channel in the route.

  3. 07.3

    The channel-list response identifies each location using:

  4. 07.4

    connection_id

  5. 07.5

    connection_name

  6. 07.6

    platform_key

  7. 07.7

    channel_id

  8. 07.8

    channel_name

  9. 07.9

    conversation_type

08

Runtime telemetry ingestion

Runtimes post Tool Call telemetry to POST /ingest/v1/agents/{agent_id}/events. The request carries only Tool Call start or pending records and Tool Result completion records; it never carries Conversation Messages, chat events, provider routing, or Communication Deliveries.

  1. 08.1

    A Tool Call is unique within (agent_id, external_id), and its status is PENDING, SUCCESS, or ERROR. Do not treat tool_name alone as Tool Call identity.

  2. 08.2

    A Tool Call event creates or idempotently updates the pending record.

  3. 08.3

    A Tool Result uses the same Runtime invocation ID to complete the matching call.

  4. 08.4

    Concurrent calls to the same tool remain distinct through separate external IDs.

  5. 08.5

    A result updates a matching Tool Call regardless of its current status.

  6. 08.6

    A result arriving before its pending Tool Call currently has no record to update and is dropped.

09

Tool Call reads

Tool Calls are read through GET /api/v1/organizations/{organization_id}/agents/{agent_id}/tool-calls.

  1. 09.1

    Tool Calls use page-based pagination, while Conversation Messages use cursor pagination. The two Activity surfaces do not share one chronological persistence model.

  2. 09.2

    Supported query controls are:

  3. 09.3

    tool_name filter

  4. 09.4

    status filter

  5. 09.5

    from_date filter

  6. 09.6

    to_date filter

  7. 09.7

    page number

  8. 09.8

    page_size limit

10

Authentication boundaries

Human Product API reads of Conversations and Tool Calls require an authenticated user, visibility of the Organization-owned and non-deleted Agent, and effective activity.read permission. Agent Access is applied before subordinate Activity data is returned, and inaccessible or cross-Organization Agents are concealed.

  1. 10.1

    Ingest writes authenticate with the Agent ID and the per-Agent Ingest bearer key generated during Agent start. Ingest checks Agent identity and key rather than human Membership or Agent Access.

  2. 10.2

    Communication Delivery claims and replies use a separate Communications protocol credential against the versioned Runtime-neutral Communications API. The Ingest key does not authorize Delivery claims or provider ingress.

11

What Activity is not

Conversation Messages and Tool Calls are operational Activity records. Neither the Conversation write path nor Tool Call Ingest writes Domain Events to the outbox.

  1. 11.1

    The Communications journal records content-free delivery and provider operations, and cost attribution is separate and does not derive from Conversation or Tool Call records. Activity records are not:

  2. 11.2

    Domain Events

  3. 11.3

    Outbox Messages

  4. 11.4

    Event Deliveries

  5. 11.5

    Security Audit Records

  6. 11.6

    Communications journal entries

  7. 11.7

    Cost or spend records

12

Activity in the web app

Agent Activity provides separate views for Conversations and Tool Calls.

  1. 12.1

    Conversation locations use Connection and channel identity, Platform and Connection names distinguish otherwise similar channels, and selecting a location reads its cursor-paginated threads and replies.

  2. 12.2

    Tool Calls can be filtered by tool, status, and date. The first page may refresh periodically while it is being observed, and results remain scoped to the selected Agent.

13

Where to look next

Use /guides/agents/communication-connections for Connection ownership and lifecycle, and /guides/agents/channel-access for the admission policies evaluated before a message is accepted.

  1. 13.1

    Use /guides/runtime-and-deployment for how Ingest and Communications credentials are generated at Agent start, /guides/domain-events-and-delivery for the separate internal event path, and /guides/costs-and-spend-attribution for cost reporting.

  2. 13.2

    Use /guides/agents/health-and-logs when a message was accepted but the Runtime produced no reply.

Documentation