Debug a bad answer

When an agent gets something wrong, the trace shows why: what it found, what it was told, which tools it called and what came back. Work through these checks in order.

1. Find the trace

Use the trace id from the stream's meta or done event (or X-Trace-Id), or search Tracing for words from the user's message. If you send your own X-Request-Id, it is on every span and in every error, so you can go from your logs straight to the trace.

# Your server sends its own correlation id…curl -N https://api.sentientone.ai/v1/chat/stream \  -H "X-Api-Key: $SENTIENTONE_API_KEY" \  -H "X-Agent-Id: $AGENT_ID" \  -H "X-Request-Id: checkout-7f3a91c2" \  -H "Content-Type: application/json" \  -d '{"message": "Can I return a worn jacket?"}'# …and logs the trace id from the first event:data: {"type": "meta", "conversation_id": "9b1c…", "trace_id": "4f2a9c1e…"}

Check these in order

1. 1

   Did retrieval find the right passages?

   Open rag.prefetch. Look at the sources and scores. If the right passage isn't there, the content may be missing or worded differently: add a Q&A pair or a snippet with the exact answer. If nothing scored above the threshold (0.30, or 0.50 when the agent has tools), no knowledge was given to the model at all. See Agent not using knowledge.

2. 2

   Was the answer from the cache?

   If answer.cached is true, the reply was a stored answer to the same first question within 15 minutes. Any change to the agent or its knowledge clears the cache; ask again after editing.

3. 3

   What did the model actually see?

   In Events, read the model input: the system prompt (with the grounding rule added for agents with knowledge), up to the last 12 messages of history and the passages. A contradiction or a vague rule in the prompt shows up here. Try a fix as a draft prompt in the Playground before publishing it.

4. 4

   Did a tool return what you expected?

   Open each tool.execute span. Check the input the model chose and the output. Remember the model sees only the first 2,500 characters of a tool's output: return compact, relevant fields.

5. 5

   Did it run out of rounds or time?

   A synthesis.forced span means the tool rounds (8) ran out or the model repeated a call, so it answered with what it had. A TIMEOUT error means the 120-second limit was hit.

6. 6

   Is it the model?

   If the inputs were right and the answer still isn't, try another model or a lower temperature in Settings. See Choosing a model.

Slow answers

• Compare time to first token with total duration. A long wait before the first token usually means retrieval, tool calls or a large model; a long tail after it is the length of the answer.
• Each tool.execute span shows its time. Slow tools slow every reply that uses them.
• Lower max tokens or ask for shorter answers in the prompt to cut the tail.