Collect and Send an Agent Bug Report from a Session¶
When an Agent responds unexpectedly, a tool stalls, the connection is unstable, or available logs are insufficient for diagnosis, you can generate a Bug Report directly from the affected Session. The report collects the current Session and Agent runtime state, sanitizes the data, packages it, and uploads it for operations or support personnel to download and analyze.
Before starting, confirm that the Agent is online and open the original Session where the issue occurred. A Bug Report collects only the current Session and does not automatically include chat content from other Sessions.
Collect and Send the Report Directly to Support¶
When you need to provide the report to support personnel, include the recipient address and symptoms in the initial request:
Collect a Bug Report for the current Session and send the download link to cs@truewatch.com. Symptom: the page keeps showing that the Agent is thinking after a tool finishes.
The Agent performs these steps:
- Collects, sanitizes, and uploads the Bug Report for the current Session.
- Obtains a temporary download link for the ZIP file.
- Sends the filename, link, and expiration time to the specified email address.
This flow avoids downloading the ZIP from the Session and then uploading it manually as an email attachment. The email contains a temporary download link, not the ZIP attachment. The recipient must download the report before the link expires.
Before sending, verify the recipient address and send the report only to people authorized to handle diagnostic data.
Collect a Bug Report for the Current Session¶
Send this message in the Session:
You can include the symptoms in the same message:
Collect a Bug Report for the current Session. Symptom: the page keeps showing that the Agent is thinking after a tool finishes.
The Agent collects, sanitizes, packages, and uploads the report. The process usually completes within two minutes. Enabling a CPU Profile may require additional time for sampling.
After upload succeeds, the ZIP file and download information appear in the Session. Reports are retained on the platform for 30 days by default, and temporary download links are valid for seven days by default. Download or forward the report before the link expires.
Approve Collection in Standard Permission Mode¶
Standard permission mode displays a tool approval before reading diagnostic data. The approval lists the collection scope, data categories, and whether a CPU Profile is included.
Approve the operation after confirming that the scope is appropriate. The Agent does not collect or upload a report if you reject the approval, cancel the request, or send a new message that stops the older run.
YOLO/Full Access mode does not display an approval dialog. The Agent collects and uploads the report directly, while the platform still records authorization audit data for the tool call.
Send an Existing Bug Report by Email¶
If the initial request only generated the report, continue in the same Session with:
The email body contains the ZIP filename, expiration time, and temporary download link. It does not include the ZIP as an attachment. The recipient must download the report before the link expires.
Control the Data Included in the Report¶
By default, the report includes:
- Sanitized and truncated messages, tool events, and effective context from the current Session.
- Recent Agent logs and runtime metrics.
- Process, container, network-probe, and build information.
- Sanitized environment variables and configuration.
- Profile, Skill, Schema, and MCP synchronization diagnostic summaries.
- Bounded goroutine dumps and Heap Profiles.
For Session attachments, the report records only the name, type, size, and content digest; it does not read attachment contents. The report does not actively collect chat content from other Sessions or package complete Skill, Schema, MCP packages, or working-directory files.
To diagnose CPU usage, explicitly request a CPU Profile:
CPU Profiles are not collected by default. You can specify 1–30 seconds. Sampling adds a small amount of Agent overhead, so enable it only when investigating CPU issues.
You can also explicitly exclude a category:
Collect a Bug Report for the current Session without environment variables or configuration snapshots.
Handle Diagnostic Reports Securely¶
The Agent masks known runtime secrets and high-confidence credentials and scans for sensitive content again before packaging. Sensitive information in free-form text cannot always be detected, so treat every Bug Report as sensitive diagnostic data.
After downloading a report:
- Share it only with responsible personnel through controlled channels.
- Do not upload it to public tickets, public code repositories, or public file-sharing services.
- Delete local copies that are no longer needed after troubleshooting.
- If the Session contains manually pasted passwords, Tokens, or personal information, notify the recipient before sending and follow your organization's data-handling policy.
Troubleshoot Collection or Upload Failures¶
Approval Remains Pending¶
Standard permission mode requires approval while the tool request is pending. If the approval is no longer available, send the collection request again.
If the Agent is configured for YOLO/Full Access but still requests approval, or reports approval_id is required for diagnostic assets, update Beak and the Agent to the same latest version and retry.
Another Report Is Already Running¶
Each Agent can collect only one Bug Report at a time. Wait for the current task to finish and retry. Do not start collection concurrently from multiple Sessions.
Report Status Is partial¶
partial means that one or more diagnostic sources were unavailable, timed out, or were removed by security checks. The remaining content was still uploaded. Download the report to review the missing items. If essential content is missing, confirm Agent permissions, log files, and network status before collecting again.
Upload Returns context deadline exceeded¶
This error can indicate that the Agent version still shares one timeout between collection and upload. Update the Agent to the latest version and retry. If the issue continues, check the connection from the Agent to Beak and review recent errors as described in View Agent Logs.
Diagnostic Assets Are Unavailable¶
If the page reports that the service does not support diagnostic assets, verify that Beak and the Agent have been upgraded to compatible versions. Restart the Agent after upgrading, then start collection again from the original Session.
Email Does Not Contain a Download Link¶
First confirm that the Bug Report was generated successfully in the Session and that its temporary download link has not expired. Ask the Agent to send the generated report again. If the email still has no link, update the Agent and verify that the email tool is configured correctly.