Observe agent work

Start with the agent and WorkItem, then inspect a task only when you need execution details. You do not need a metrics collector to check one piece of work.

Before you start

Know the target agent ID and run these operator commands on the runtime host, for example through an authorized SSH session. A remote TUI connection does not retarget later shell commands. The examples use builder; replace it with your agent. Include --agent consistently so you do not read the default agent by mistake.

1. Locate the objective

holon agent status builder
holon work-item list --agent builder
holon work-item get WORK_ITEM_ID --agent builder

Copy WORK_ITEM_ID from the list. Check the objective, plan status, todo list, wait reason, and result fields. current means focus, not proof that the item is running. A yielded item is parked while another item runs.

If no item matches, the work may have been a short untracked request. Inspect recent output and the request's message or task ID rather than creating a new WorkItem merely to observe it.

2. Read the latest report or progress

holon tail --agent builder --limit 10
holon tail --agent builder --include-progress --follow \
  --timeout-ms 5000 --max-events 100 --max-bytes 65536

The first command reads recent briefs. The second opts into persisted assistant progress and returns bounded NDJSON ending in an end receipt. Save its cursor if you need to continue:

holon tail --agent builder --include-progress --follow --cursor 'RETURNED_CURSOR'

A follow timeout means the observation window ended, not that the work failed. On a reset or gap, take a fresh snapshot without a cursor. If the runtime does not advertise agents.conversation-read.v1, use the default brief snapshot.

Progress may be absent even while a command runs. These reads do not wake the agent, consume a task result, or isolate output by task; one agent's output can include several tasks.

3. Inspect a specific task

Use the task ID from the execution receipt or task list:

holon task list --agent builder
holon task status TASK_ID --agent builder
holon task output TASK_ID --agent builder

Match the task owner and work_item_id with the objective. The task keeps its original owner even after the agent switches focus. Inspect the exit result and output for failures; a terminal task is not necessarily successful.

For an agent waiting on task completion, use WaitFor(wake=task_result) with that ID. Repeated status reads are for diagnosis, not a replacement for the agent's durable wait.

4. Retrieve the accepted result

Read the WorkItem again after it completes. Confirm state=completed and use result_brief_id to identify the canonical completion report. Recent briefs may contain acknowledgements and waiting reports as well as results; do not assume the latest text belongs to your objective.

The report should identify changes, verification, remaining limits, and artifact locations. Inspect those artifacts at the returned workspace or worktree path. A file with the same name in another checkout is not necessarily the deliverable. For exact report retrieval over HTTP, see Automate over HTTP.

5. Escalate only if needed

If status and reports do not explain the problem, inspect a bounded transcript:

holon transcript --agent builder --limit 30

Record the agent, WorkItem, task, and message IDs plus the observed failure. Redact secrets and unrelated content before sharing transcripts or logs.

Success means you can identify the objective's current state or completion report, locate its artifacts, and distinguish unfinished work from an observation timeout. For stalled execution, use Troubleshooting. For runtime-wide telemetry, use Configure observability.