Observe Agent Activity

What Agent activity contains

Agent activity currently consists primarily of persisted Conversation Messages and Tool Calls. Each has its own view and its own fields.

The Agent detail page currently exposes four activity-related tabs to authorized users: Conversations, Tool calls, Logs, and Activity. This guide covers Conversations and Tool calls.

These views appear only when you have effective activity.read permission for the Agent. They are not automatically available to every Organization Member.

Runtime logs, Agent health, and cost records are separate data sources. They are not Conversation Messages or Tool Call records, and they are not derived from them.

How activity reaches Agent Barn

Conversations and Tool Calls share the Agent detail experience, but they do not share a write pipeline or a persistence identity.

Conversations come from Communications

1. Platform provider Slack, Microsoft Teams, Telegram, or Discord delivers an event to the Communication Connection that owns that provider identity.
2. Platform Plugin The shipped plugin authenticates the provider boundary where applicable, normalizes the payload, and evaluates the Connection admission policy.
3. Communications Gateway Accepted messages create durable Communication Deliveries, and Communications persists the canonical inbound Conversation Message.
4. Runtime reply through the Communications protocol The Runtime claims the Delivery over the Runtime-neutral Communications protocol and submits its reply, which Communications persists as the canonical outbound Conversation Message.

The sequence reads top to bottom in four stages: a Platform provider delivers an event, the Platform Plugin normalizes and admits it, the Communications Gateway persists the canonical inbound Conversation Message alongside a durable Delivery, and the Runtime's reply returns through the Communications protocol to be persisted as the outbound message.

Ingest does not accept or persist Conversation Messages. For the complete delivery architecture, see Activity, conversations, and runtime telemetry.

Tool Calls come from Ingest

1. Hermes or OpenClaw Agent Runtime The Runtime reports Tool Call and Tool Result telemetry as it executes tools, authenticating with the Agent ID and the per-Agent Ingest key generated when the Agent starts.
2. Ingest API A separately served internal API that accepts Tool Call telemetry only. Duplicate pending-call identities are handled idempotently.
3. Persisted Tool Call records Ingest writes Tool Calls to their own repository, separate from Conversation persistence.

Tool Calls are not provider messages, Communication Deliveries, or Domain Events. Their statuses are PENDING, SUCCESS, and ERROR.

Activity reads do not connect to the live Agent pod or parse its files on demand. Persisted activity therefore remains available while an Agent is stopped, as long as you still have access to the Agent.

Permissions and visibility

Conversation and Tool Call reads require both of the following:

1. Visibility of the Organization-owned, non-deleted Agent in the active Organization.
2. The activity.read Permission.

The locked Agent Viewer, Editor, and Owner roles all include activity.read. Organization Owners and Admins hold implicit authority over every Agent in their Organization.

An Organization Member without applicable direct or General Agent Access cannot bypass Agent visibility through an activity endpoint. If you can view the Agent but lack activity.read, the Conversations, Tool calls, Logs, and Activity tabs are hidden.

Activity reads are subordinate to the Agent Access boundary, and inaccessible, deleted, and cross-Organization Agents are concealed. Knowing an Agent, Connection, channel, or Tool Call identifier does not bypass Agent Access.

Platform View

Platform View may expose bounded aggregate statistics, such as message counts or the number of active Agents. It does not expose:

• Message content
• Sender identity
• Channel identity
• Session identity
• Tool arguments
• Tool results
• Tenant runtime logs

A Platform Administrator needs a real Organization Membership and applicable Agent access to inspect an individual Agent’s activity content. See Manage roles and permissions.

Open the Activity views

1. Select the Organization

Confirm that the Organization selector shows the Organization that owns the Agent.

2. Open the Agent

Select the Agent from the Organization dashboard.

3. Choose an activity tab

The Agent detail page provides Conversations, Tool calls, Logs, and Activity.

This guide covers Conversations and Tool calls. See Review Agent health and logs for Runtime logs and health.

Review conversations

This illustration shows the layout, not product output. The left column lists the Channels the Agent has messages in, then the Direct Messages, one of which shows an unresolved platform ID. The right column shows the selected #support conversation with its From and To filters above a thread: an inbound message from Alice Example at 08:30:00, and the Agent’s outbound reply at 08:30:08.

1. Open Conversations

Select Conversations from the Agent detail page. The sidebar separates activity into Channels and Direct Messages.

Channel labels use a # prefix. Direct Messages use the resolved person or conversation name where available. When Agent Barn cannot resolve a display name, it shows the provider ID as a fallback.

Each location also displays its Communication Connection name underneath. That label matters when an Agent has several Connections exposing similar channel names.

2. Select a channel or direct message

Select a conversation from the sidebar. A selected location is identified by both its connection_id and its channel_id, and the selection key is equivalent to:

<connection-id>:<channel-id>

Channel ID alone is not unique, because an Agent may have multiple Connections, multiple same-Platform Connections may expose the same provider channel ID, and different Platforms may use overlapping identifier formats. Both identifiers are preserved in the URL, so the view is easy to revisit or send to another authorized operator.

3. Identify message direction

Every message has one of two directions. The interface labels each message in text, so direction never depends on color alone.

Inbound messages are labeled with the resolved sender name or sender ID. Outbound messages use the Agent’s name.

4. Review threads

Threaded messages are grouped under their root message. Select the thread header to expand or collapse its replies; the header is a button, so it responds to Enter and Space as well as a pointer.

A thread block displays the root message, the reply count, and the replies in chronological order. Unthreaded messages appear as independent roots.

5. Load earlier history

The newest conversation page appears first, but messages inside the visible page are shown chronologically. Select Load earlier conversations to retrieve older thread groups.

When no older page remains, the interface shows:

Beginning of conversation

Filter conversation history

Use the From and To controls above the selected conversation. The interface accepts local date and time values and converts them to ISO 8601 timestamps.

From is inclusive

A message is included when:

occurred_at >= from_date

To is exclusive

A message is included when:

occurred_at < to_date

Recommended investigation window

When investigating an event reported at 14:15, start with a slightly wider range:

From: 14:05
To:   14:25

A wider range helps capture the message that initiated the task, earlier thread context, Agent responses, and nearby retries or follow-up messages.

Review tool calls

Select Tool calls from the Agent detail page. Tool Calls are ordered newest first, and the table shows four columns:

Expand a call

Select a Tool Call row to inspect its Arguments and Result, rendered as formatted JSON. The row is a native disclosure control, so it opens with Enter or Space as well as a pointer. The result section is omitted when no result has been reported.

{
  "repository": "example/repository",
  "issue": 42
}

{
  "title": "Example issue",
  "state": "open"
}

This illustration shows an expanded Tool Call row, not product output. The collapsed row carries the time, the tool name, the status as the word Success, and the duration. Expanding it reveals the Arguments and Result JSON.

Filter by tool name

Use Filter by tool name to find calls such as:

read
bash
github
jira
web

Tool-name matching is partial and case-insensitive.

Filter by status

Choose all statuses, Pending, Success, or Error.

Filter by date

Use the From and To date controls. As with Conversations, From is inclusive, To is exclusive, and local date values are converted to ISO 8601 timestamps.

Move through pages

The interface displays 20 Tool Calls per page. Use the pagination controls to reach older results.

Automatic refresh applies only to the first page, which refetches approximately every five seconds.

Interpret tool-call statuses

Investigate an Agent task

Use this sequence when a user reports an unexpected response or action.

1. Establish the time window Record the Organization, Agent, chat platform, channel or direct message, approximate local time, reporting user, and expected behavior. Allow for timezone differences between the reporter and the stored timestamps.
2. Review the conversation Open the relevant channel or direct message and set a narrow date range. Identify the initiating inbound message, thread context, the Agent response, follow-up messages, and whether the response landed in the correct chat.
3. Review Tool Calls Apply the same window and look for expected tools that were never called, unexpected tools, repeated calls, error results, long-lived Pending calls, and unusually long durations.
4. Inspect arguments and results Expand the relevant rows and compare the requested resource, the actual resource identifier, the provider profile or repository, read versus write, the returned status, and whether the result matches the outbound response.
5. Compare runtime health and logs Check the Logs tab for telemetry delivery errors, provider errors, runtime crashes, correlation warnings, buffer overflow warnings, and retry exhaustion. Review Agent health for a restart or crash during the task.
6. Verify external state For consequential actions, confirm the outcome in the external provider: that the comment exists, the issue changed, the email was sent, or the file was written.
7. Record the finding Capture timestamps, the conversation channel, tool names, Tool Call IDs, statuses, sanitized errors, the external verification result, and the remediation required. Do not copy secrets or unnecessary message content into tickets.

Understand freshness and gaps

The two Activity surfaces refresh differently, because they are written by different services.

Expected freshness

Conversation Messages are persisted by Communications as each accepted message and reply is processed. The first Tool Call page refetches approximately every five seconds.

Conversation queries do not use that automatic polling behavior. Reload the page or reopen the view when you are waiting for newly persisted messages.

Tool Call delivery retries

Tool Call telemetry is delivered to Ingest with a limited number of retries, so a Tool Call can be missing after a sustained outage. Inspect Runtime logs for messages such as:

telemetry-push buffer full
telemetry-push flush failed
telemetry-push dropped events

Conversation history is unaffected by that path, because Communications persists it independently of Ingest.

Idempotency

Provider message identity is unique within its Connection, and pending Tool Call identities are handled idempotently. A repeated delivery should not normally create duplicate visible activity.

Correlation safety

A Runtime reply is bound to the source Communication Delivery, so it cannot be recorded against another Connection, channel, or direct message. The Runtime does not choose the outbound destination.

Tool results are matched to pending calls using the Runtime’s per-invocation identifier. A result received before its matching pending call currently has no record to update and is dropped, which can leave long-lived Pending calls during failures.

Name enrichment

Platform Plugins record provider IDs and then attempt to resolve readable names, best effort, before canonical persistence. Enrichment is invoked by Communications, not by Ingest.

Lookup results may be cached briefly. A raw ID does not mean the message is invalid; it can mean the provider directory was unavailable or the credential lacked directory access. A lookup failure does not delay or reject an otherwise accepted message, stable provider IDs remain authoritative, and a duplicate delivery may fill a missing name but does not erase an existing one.

Conversations versus Connection diagnostics

The Conversations tab displays accepted canonical message content. It is not a delivery diagnostics surface.

Communication diagnostics separately provide:

• Connection health
• Content-free operational journal entries
• Policy rejections
• Delivery attempts
• Retries
• Dead letters
• Reconnect and recovery information

Journal entries are never merged into the Conversation timeline. See Communication Connections for where those diagnostics live.

Activity, logs, costs, and audit records

These data sources answer different questions.

Conversation Messages and Tool Calls are not cost records, spend attribution sources, Domain Events, Outbox Messages, Event Deliveries, or Security Audit Records. Costs are not calculated from Conversation Message or Tool Call counts.

See Costs and spend attribution for how spend is reported, and Domain Events, outbox, and delivery for the separate internal event path.

API reference

List conversation channels

GET /api/v1/organizations/{organization_id}/agents/{agent_id}/conversations/channels

[
  {
    "connection_id": "018f0000-0000-7000-8000-00000000000a",
    "connection_name": "Slack: Support workspace",
    "platform_key": "slack",
    "channel_id": "C0123456789",
    "channel_name": "support",
    "conversation_type": "CHANNEL"
  },
  {
    "connection_id": "018f0000-0000-7000-8000-00000000000a",
    "connection_name": "Slack: Support workspace",
    "platform_key": "slack",
    "channel_id": "D0123456789",
    "channel_name": "Alice Example",
    "conversation_type": "DM"
  }
]

The channel list identifies each location using connection_id, connection_name, platform_key, channel_id, channel_name, and conversation_type.

Read conversation threads

Message reads are scoped to one Connection and channel. Conversation pagination is cursor-based, and the API defaults to six thread groups per page.

GET /api/v1/organizations/{organization_id}/agents/{agent_id}/conversations/connections/{connection_id}/channels/{channel_id}/messages?page_size=6

There is no current route that reads messages using agent_id and channel_id without a connection_id.

Optional parameters:

from_date=2026-08-29T08:00:00Z
to_date=2026-08-29T09:00:00Z
before_occurred_at=2026-08-29T08:30:00Z
before_id=018f0000-0000-7000-8000-000000000001
page_size=6

{
  "threads": [
    {
      "root": {
        "id": "018f0000-0000-7000-8000-000000000001",
        "direction": "INBOUND",
        "thread_id": null,
        "sender_id": "U0123456789",
        "sender_name": "Alice Example",
        "content": "Summarize the latest deployment status.",
        "occurred_at": "2026-08-29T08:30:00Z"
      },
      "replies": [
        {
          "id": "018f0000-0000-7000-8000-000000000002",
          "direction": "OUTBOUND",
          "thread_id": "1756456200.000000",
          "sender_id": null,
          "sender_name": null,
          "content": "The latest deployment completed successfully.",
          "occurred_at": "2026-08-29T08:30:08Z"
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": {
    "before_occurred_at": "2026-08-29T08:30:00Z",
    "before_id": "018f0000-0000-7000-8000-000000000001"
  }
}

Use the complete next_cursor in the next request. The before_id value is the deterministic tie-breaker when several thread roots share a timestamp.

List Tool Calls

Tool Call pagination is page-based.

GET /api/v1/organizations/{organization_id}/agents/{agent_id}/tool-calls?page=1&page_size=20

Optional filters:

tool_name=github
status=ERROR
from_date=2026-08-29T08:00:00Z
to_date=2026-08-29T09:00:00Z

{
  "page": 1,
  "page_size": 20,
  "total": 1,
  "items": [
    {
      "id": "018f0000-0000-7000-8000-000000000003",
      "agent_id": "018f0000-0000-7000-8000-000000000004",
      "session_id": "session-redacted",
      "tool_name": "github_issue_get",
      "arguments": {
        "repository": "example/repository",
        "issue": 42
      },
      "result": {
        "title": "Example issue",
        "state": "open"
      },
      "status": "SUCCESS",
      "occurred_at": "2026-08-29T08:30:02Z",
      "completed_at": "2026-08-29T08:30:03Z",
      "duration_ms": 921
    }
  ]
}

Tool Calls are ordered by occurred_at descending. The example above uses placeholder identifiers and content: no real message, session, or credential data.

Troubleshooting

Security and privacy

Next steps

After reviewing Agent activity:

1. Compare unexpected Tool Calls with runtime logs.
2. Verify consequential changes in the external provider.
3. Correct Agent configuration, Skills, credentials, or access as needed.
4. Repeat the task with a controlled test.
5. Review model usage and spend.
6. Continue to Review costs.

Agent Activity, wake grouping, and triggers

The Activity tab answers what an Agent has been doing over time by grouping model calls into distinct wakes — bursts of model calls occurring close together.

The Activity tab also displays live container runtime diagnostics independently of the usage window, surfacing termination codes and previous-container logs even when no billable calls occurred.