Execution model

Imagine a support agent investigating a damaged order. The user sends a message, the model requests an order lookup, the tool returns facts, and the model asks which item was damaged. That work has several identities.

Session: durable conversation and state
  Interaction: one admitted run or continuation
    Model step: one decision in the model/tool loop
      Provider attempt: a concrete try at that model call
      Tool round: the calls requested by the accepted response
        Tool call: one independently recorded invocation

A provider retry is another attempt; it does not become a second user request. Parallel tools share a round but have distinct call identities. Pausing for user input ends that interaction with durable state that a later continuation can address.

Why identities matter

Use the session identity to retrieve the conversation. Use the round and call identities to inspect one pending tool approval or reconcile a result. Keep a business operation’s stable idempotency identity when a downstream service must deduplicate effects. The runtime’s execution identity and the downstream service’s action identity serve different responsibilities.

If a provider request times out, inspect whether an attempt has a known terminal result before deciding what can safely retry. If a tool call mutates an external service, a missing local terminal event leaves an outcome to reconcile.

Events and outcomes

CayuApp.run(...) produces an asynchronous event stream. Consume it incrementally for ongoing work. run_to_completion(...) consumes the same runtime path and returns a typed RunOutcome; it retains events and suits bounded runs.

Runtime failures can appear as terminal session.failed events. A stream iterator completing does not by itself mean success. Check the terminal state and relevant evidence. Read sessions and observability next.