Trace and Debug Agent Tool-Call Failures

An agent fails or receives an exception while calling an external tool. The visible result does not show whether the failure occurred while preparing the request, reaching the tool, executing it, parsing its response, or retrying an earlier attempt. Design end-to-end tracing for this tool-call path so an engineer can reconstruct a failed request and distinguish the original failure from behavior introduced by retries. ### Constraints and Clarifying Questions - A single agent request may make several logical tool calls, and each logical call may have several attempts. - External tools may return errors, time out, or produce a response the agent cannot parse. - Clarify whether a tool supports trace-context propagation and whether it can change external state. - Inputs and outputs may contain secrets or personal data; explain what to record without requiring complete raw payload logging. - No tracing vendor, retry count, or latency target is prescribed. ```hint Identify the unit of work A user request, a logical tool call, and a network attempt are different units. Decide which identifier lets you group each unit without making separate attempts look like duplicate logs. ``` ### What a Strong Answer Covers - Trace and span relationships from the agent request through each tool-call attempt. - Timing, sanitized request/response metadata, exception details, and response status sufficient to locate the failure stage. - How retry decisions and delays appear in the trace, including the possibility that a timed-out operation actually completed. - A concrete investigation sequence for distinguishing transport, execution, and response-parsing failures. ### Follow-up Questions - How can you correlate the call when the external tool does not accept your trace headers? - What should happen after a timeout if the tool creates an external resource and offers no idempotency guarantee? - How would you retain useful failure evidence while limiting storage and avoiding sensitive payload capture?