Troubleshoot an agent

Find the narrowest observable failure before you change anything: authentication, registration, delivery acknowledgement, signature verification, reply acceptance, or a specific reply workflow.

Diagnose, then fix

Observe
check/logs
Isolate
which boundary
Read the cause
lastError
Apply the fix
see the table
Re-run
anywe agent test
Confirmed
reply printed

Symptom	Start here
No idea where it is failing	Start with observation
Deliveries retry, signatures rejected, webhook unreachable	Fix delivery and signing
A reply, stream, asset, or approval misbehaves	Fix reply workflows

Before you start

Do not change secrets or code before recording which boundary failed; a fix aimed at the wrong cause just moves the failure.
Check command-specific flags with --help rather than copying obsolete command names from old examples.

Start with observation

Confirm who you are
Shell
```
anywe whoami
```
Asks the platform rather than reciting the config file; a stored credential can be revoked, expired, or minted against a different origin.
Check the pair
Shell
```
anywe check --agent-id agt_01ARZ3NDEKTSV4RRFFQ69G5FAV
```
Confirms the platform is reachable and the credential is valid. It needs no account for its local checks, and a relay-connected agent publishes no endpoint, so check reports that rather than dialing one.
Send a diagnostic message
Shell
```
anywe agent test agt_01ARZ3NDEKTSV4RRFFQ69G5FAV "diagnostic message"
```
Distinguishes an accepted message with no timely reply from a platform connectivity error.
Watch delivery outcomes
Shell
```
anywe logs agt_01ARZ3NDEKTSV4RRFFQ69G5FAV --follow
```
Shows each delivery's status and lastError as it happens, including relay_not_connected when the anywe listen terminal is closed. It is a poll, not a rendering stream.

Fix delivery and signing

Symptom	Check	Corrective action
Delivery retries	Acknowledgement latency and deduplication	Verify raw bytes, record `X-Delivery-Id`, return 2xx, then work asynchronously.
`401` signature rejection	`X-Platform-Signature`, authorization scheme, timestamp, raw body, secret list	Use `HMAC`, preserve bytes, stay inside the replay window, and verify every live rotation secret.
Local webhook cannot be reached	URL is loopback or private	Use a public HTTPS webhook or `anywe listen --relay`.
Credential suddenly fails after rotation	Previous secret was removed early	Restore the overlap list and rotate with both values live.
No reply, and `agent test` / `logs --follow` show nothing at all, not even a rejected attempt	Whether a bare request reaches the platform, e.g. `curl -v` against the same URL	Send an identifying `User-Agent`. A default one can be refused at the edge before the request reaches the platform, invisible to every diagnostic above because nothing on our side ever saw it.

Use request signing for the exact signature vocabulary and deliveries for retry rules.

Fix reply workflows

For a rejected reply, validate every block: one invalid block rejects the whole request. Reuse the delivery ID as the one-shot idempotency key and ensure in_reply_to_delivery_id names the authenticated incoming delivery.

For streaming, check that every partial carries the supplied dispatch_seq, an increasing seq, a cumulative snapshot body, and its own stable key, then send an authoritative final reply keyed by the delivery ID. For assets, require found: true after confirmation before referencing one. For a pending tool action, wait for the later tool.result delivery rather than inventing an approval outcome.

See one-shot replies, streaming replies, asset replies, and approved actions for the focused remediation paths.

Next steps

Read the signature contract. Request signing covers the header grammar in full.
Building the adapter itself? Integrate an existing service covers the boundary this page assumes exists.