Skip to content
Start ReadingGitHub
Chapter 26Building blocks

Results, failures, side effects, and confirmation

Explain tool outcomes, uncertain failures, side effects, confirmation and idempotent retries.

Learning objectives
  • Classify tool effects and distinguish transport errors from action outcomes.
  • Explain idempotency keys and their limits.
  • Trace a proposed action through confirmation and execution.

The shop assistant now offers to reserve two lamps. The inventory service accepts the reservation, but its reply never reaches the assistant. Should the assistant try again? A fresh request might reserve two more lamps. Saying “the reservation failed” would also be misleading: the caller has lost the receipt, not necessarily the reservation.

Unlike retrieval, which primarily supplies evidence, actions can change the environment. Handling their results requires a clear account of what the runtime knows.

A result is the output of an invocation. Our result contract distinguishes succeeded, invalid_request, out_of_stock, pending_confirmation and unknown. An ordinary negative business outcome, such as insufficient stock, can be delivered successfully. A network failure can leave the business outcome unknown.

Return the observed data, operation identifier and relevant timing, rather than only “done.” A later lookup of stock cannot by itself identify whether our reservation caused the change. An operation-specific receipt is more useful.

A timeout is a limit on how long the caller waits. It does not prove that remote work stopped. The Agents SDK supports timeout configuration for async function tools and can return error information to the model or raise an exception to the runtime. The surrounding application still needs to interpret the external outcome. SDK tools.

A side effect is an observable change beyond returning a value. For our shop, use this functional classification:

Capability Business state changed? Can repeating it add another effect? Useful next step after an uncertain reply
Read stock No reservation change No new reservation Repeat the read if still useful
Set delivery preference Yes Same value may converge, notifications may repeat Inspect the contract and current version
Reserve two lamps Yes Yes, without duplicate handling Query or retry the same logical operation
Send a pickup message Yes, externally visible A second message may be sent Inspect delivery record

A read can still create logs, incur charges or return a different value later. “Read-only” here describes the business resource, not the absence of every possible effect.

Robots compare reading stock, setting a preference and making a reservation, with different repeat effects.

Figure 1. Read across each row. First ask what changes, then what a repeat would do. Recovery depends on this contract, not only on whether a response contains an error.

Idempotency means repeated application has the same intended effect as one application. An idempotency key identifies repeated attempts at the same logical operation. It is different from a model call ID: separate call attempts can belong to one reservation.

Stripe API v1 illustrates a service-side contract: it stores an executed response for a key, checks parameters on reuse and applies a retention period. The behavior is specific to that API. Idempotent requests.

In our design, generate the key before the first reservation attempt, preserve it with the pending operation, and reuse it only with the same parameters. Changing the quantity means a different operation. A local dictionary teaches the idea but does not handle crashes, simultaneous callers or a remote service that ignores the key.

Confirmation is a person’s decision on a concrete proposed action. Show “Reserve two lamps at this shop” before executing. The runtime records a pending decision and resumes or cancels that proposal. A changed action needs a new decision; the old decision was about a different request.

The SDK exposes pending tool approvals as interruptions and supports decisions and resumption through RunState. This packages pause and resume behavior; it does not turn confirmation into a successful reservation. Human-in-the-loop.

The offline reservation example begins with four lamps. Before confirmation, stock stays at four. After approval, the service reserves two but simulates losing its reply. The caller sees a timeout while stock is already two. A retry using the original key returns the stored receipt without taking more stock. Reusing the key with a different quantity returns key_conflict.

Expand minimal Python implementation
if key in receipts:
old_request, result = receipts[key]
if old_request != request:
return {"status": "key_conflict"}
return dict(result)

This is one step in the example, not a complete production implementation. Durable storage, concurrency and atomic recording of the effect and receipt are outside this small mock.

Retries can improve recovery from temporary failures, but only when the operation contract permits them. Invalid arguments usually need correction, not repetition. Limit retry count and elapsed time; repeated attempts should not keep a run alive forever.

Two independent reads may run in parallel. A reservation and a cancellation of that reservation have an ordering dependency. Two writes to the same stock count can also conflict even if the model requested them together.

Tools have a lifecycle: their descriptions, handlers and result contracts may change. Keep enough version information to interpret a pending request when the runtime resumes later. An unavailable tool should produce an explicit outcome, not a silent substitute.

Confirmation, duplicate handling and authority are separate parts of the system. Identity and authorization develops the functional authority model. Pass 2 examines unsafe calls and excessive agency in tools, identity and credentials.

  • A timeout may leave an action outcome unknown.
  • Classify side effects before choosing retries or parallel execution.
  • Preserve the same operation key across retries with unchanged arguments.
  • Confirmation decides whether to proceed; execution produces the receipt.
Check your understanding

Does a timeout prove that a reservation failed? No. The operation may have committed before its response was lost.