> ## Documentation Index
> Fetch the complete documentation index at: https://vida.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookbook: Investigate Agent Work

> Trace a customer-impacting issue across Tasks, logs, conversations, and destination-system evidence.

Use this workflow when an Agent interaction, Task, scheduled run, or Computer operation produced an
unexpected result. The goal is to establish what happened before changing production state.

## 1. Bound the incident

Collect:

* selected account and Agent account
* exact start and end time with timezone
* customer or Contact identifier
* expected and observed behavior
* known Task, room, conversation, or log IDs
* the affected external system

Do not start with an organization-wide unbounded log export.

## 2. Find the initiating work

If a Task ID is known, [read the Task](/docs/api-reference/tasks/fetch-a-specific-task) first. Otherwise:

* [query Tasks](/docs/api-reference/tasks/fetch-all-tasks) by bounded time, Agent, Contact, external
  reference, recipient, state, or outcome
* [query logs](/docs/api-reference/conversation-logs/query-conversation-logs) for the same time and
  account
* request only the fields needed for the investigation

Keep Task IDs, room IDs, conversation UUIDs, Agent account IDs, and `agentConfigId` values distinct.

## 3. Expand the evidence

For communication work, inspect every relevant Task attempt and its log or conversation reference.
For a repeating Task, inspect the selected run and its `chatRef`. For Computer work, read the linked
chat to see instructions, progress, tool calls, and the final result.

Use the appropriate conversation operation:

* [read one complete conversation](/docs/api-reference/conversations/get-a-conversation)
* [read room messages](/docs/api-reference/messaging/fetch-room-messages)
* [fetch several conversations](/docs/api-reference/conversations/fetch-multiple-conversations) only
  for a bounded known set

## 4. Verify the external result

Check the system that owns the claimed effect: CRM record, appointment, payment, email, message,
browser destination, file, or other business system. Separate these cases:

* the Agent never attempted the action
* the action was attempted and rejected
* the destination accepted it but Vida did not receive confirmation
* the action succeeded and only the summary or reporting value is wrong

## 5. Establish the cause and scope

Build a timeline from source timestamps. Identify the Agent version, experiment variant, Task
attempt, channel, and integration involved. Compare a small number of successful interactions when
needed to determine whether the issue is isolated or systematic.

For a Computer-specific runtime failure, check health and recent diagnostics only after the linked
work record indicates an infrastructure or tool problem. Do not restart, repair, or upgrade a
Computer merely because a business action failed.

## 6. Remediate and prove the fix

Choose the smallest change supported by the evidence. Test it with a safe reproduction, verify the
destination effect, and then monitor the original failure condition over a bounded period.

Do not blindly retry a write when its prior result is uncertain.

## Incident packet

Return:

* observed impact and affected scope
* timeline
* Task, log, conversation, and Agent references
* external-system evidence
* established cause or clearly labeled uncertainty
* remediation performed or recommended
* verification result

Keep raw service diagnostics separate from the customer-facing explanation.