Skip to content

Interactions

An Interaction is one durable step in a model conversation. It can represent a user message, an assistant response, a set of tool calls, or the tool results returned to the model. A list of interactions therefore holds both the conversation and the work performed during it.

Provider APIs variously call this state messages, contents, responses, or interaction history. A11 keeps the ordered turns in one application-owned model while retaining provider-native content needed to continue a turn.

Create a portable user turn

The following envelope is understood by every included backend. a11.to_chunk keeps the content within A11’s ordinary serialisation model.

import a11
from a11.sdk.llm import Interaction, Role

question = Interaction(
    role=Role.USER,
    content=[
        a11.to_chunk(
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Which orders are delayed?"}
                ],
            }
        )
    ],
)

Keep the user interaction and the interactions emitted by the model in order. Feed that list into the next call to continue the conversation:

history: list[Interaction] = []
history.append(question)
history.extend(model_interactions)

When an assistant interaction requests actions, it remains unchanged. A11 runs the calls and appends a separate user interaction containing their outputs; the model continues from that new turn. The included interact_with_* actions perform this step and emit both interactions on new_interactions.

Provider responses may retain their native content shape so no information is lost. A11 also records which backend produced them and can normalise text, images, tool calls, and tool results when a later turn switches provider.

Treat interactions as application state

Interactions are Pydantic models, so they can be validated, copied, and stored as JSON alongside the rest of an application’s state:

payload = interaction.model_dump_json()
restored = Interaction.model_validate_json(payload)

An interaction records one step; it is not a live model connection. Streaming tokens travel through action output nodes. The completed interaction supports the next step, auditing, and replay.

Read the schema

Interaction is registered as a11.sdk.Interaction. Its fields use A11 wire types, so the same record can cross Python, TypeScript, and native action boundaries. In Python, its effective shape is:

Interaction(
    id: str,
role: Role,
created_at_millis: int | None,
previous_interaction_id: str,
model: str,
status: Status | None,
system_instructions: list[Chunk],
action_configs: dict[str, A11ActionConfig],
content: list[Chunk],
action_calls: list[ActionMessage],
action_inputs: dict[str, list[NodeFragment]],
action_outputs: dict[str, list[NodeFragment]],
backend_specific_metadata: dict[str, bytes],
usage_metadata: UsageMetadata | None,
)

The identity and sequencing fields place the interaction in a conversation:

Field Default Meaning
id A new UUID Identifies this interaction and supplies the target for previous_interaction_id.
role Role.USER Identifies the producer: user, model, or system. Assistant interactions use Role.ASSISTANT, whose wire value is model.
created_at_millis None Records creation time as milliseconds since the Unix epoch when the producer supplies it.
previous_interaction_id "" Links to the preceding interaction. Stateful providers can use this link to resume server-side conversation state.
model "" Names the model that produced the interaction. User and tool-result interactions commonly leave it empty.
status OK Records the outcome of this conversational step. A failed status remains data about the turn; deserialisation reports its own status separately.

The prompt and response fields carry model-facing data:

Field Default Meaning
system_instructions [] Holds system prompt material as chunks, separate from conversational content.
action_configs {} Maps an action name to routing and header autofill settings. Each A11ActionConfig selects a peer and supplies binary headers needed when that action runs.
content [] Holds text, images, or provider-native response structures as chunks. Each chunk's metadata describes how to decode its bytes. Consecutive chunks may omit a repeated MIME type.

Tool work uses the action protocol directly, with ActionMessage and NodeFragment as its records:

Field Default Meaning
action_calls [] Lists the ActionMessage values requested by the model. Each message identifies the action call, action name, port mappings, and call headers.
action_inputs {} Maps an action-call ID to the NodeFragment values written to that call's input ports. Fragment IDs select concrete port nodes; sequence and continuation fields preserve streaming order.
action_outputs {} Maps an action-call ID to output fragments returned by the action. These usually appear on a separate user interaction that follows the assistant's call request.

The remaining fields retain accounting and provider details:

Field Default Meaning
backend_specific_metadata {} Stores opaque byte values needed by one backend, such as its producer name, stop reason, container ID, or resumable session ID. JSON serialisation represents the bytes as base64.
usage_metadata None Stores provider-independent input, output, total, cached-input, cache-write, and reasoning token counts. Unreported counters remain None.

The schema permits content, action calls, and status information in the same interaction. role records provenance; every role admits the same payload fields. The ordered interaction list remains the conversation record, while previous_interaction_id makes the link explicit for backends that address stored state by ID.

Interpret token usage

Read interaction.usage_metadata for the provider's reported consumption. A11 normalises the counters so the same field has the same meaning across backends. These counts describe model input and generation, including provider prompt overhead, rather than the size of the stored interaction.

Counter Includes Excludes
input_tokens Ordinary, uncached prompt tokens. Reported cache reads, separately reported cache writes, and generated output.
cached_input_tokens Prompt tokens reused from a provider's cache. Ordinary input, cache writes, and output.
cache_write_tokens Prompt tokens written to a cache, when reported separately. Ordinary input, cache reads, and output.
output_tokens All generated tokens, including tool arguments and reasoning/thinking. Prompt tokens, including cache reads and writes.
reasoning_tokens The reasoning/thinking portion of output_tokens, when reported. Other generated output. This is a subset of output, not an additional count.
total_tokens The provider's total for the interaction, preserved when supplied. Otherwise, a total derived from input, cache, and output counts where available. No separately supplied breakdown should be added to this total again.

Cache reads reuse prompt material already stored by the provider; cache writes store prompt material for later reuse. Both are input to the model and remain part of the prompt even though A11 records them outside input_tokens. A cache hit therefore reduces ordinary input without removing those tokens from the prompt or the reported total. Providers may charge cache reads, cache writes, ordinary input, and output at different rates; a token total alone is not a monetary cost.

When the provider's total consists of these four categories, the relationship is:

prompt tokens = input_tokens + cached_input_tokens + cache_write_tokens
total_tokens = prompt tokens + output_tokens
reasoning_tokens <= output_tokens

Keep the provider's total_tokens when supplied, even if its additional usage categories or incomplete breakdown prevent this calculation. An unreported counter is None (unknown); a reported 0 means none were counted.

For example, these fully reported counts illustrate cache use and reasoning:

Example Input Cache read Cache write Output Reasoning (within output) Total
Cache hit 100 900 0 50 0 1,050
Cache creation 100 0 900 50 0 1,050
Reasoning response 40 0 0 124 119 164

The first two requests each have a 1,000-token prompt and 50 output tokens. The reasoning response generates 5 response tokens and 119 thought tokens: output is 124, and total is 164. Adding reasoning to output again would count the thoughts twice. Gemini reports response and thought tokens separately; A11 combines them into output_tokens.

Sum total_tokens once per interaction for reported consumption, and sum output_tokens for generated tokens. Count each interaction ID once when processing repeated delivery or replay.

usage_scope is request for one model call or turn for all model calls in a user turn. Codex and Claude Code report turn usage; Claude Code includes each model in its result's per-model usage map when available. A turn total includes repeated prompts across tool rounds. context_tokens, when supplied, describes the last model request's full input, including cache reads and writes, plus output. For example, two tool-round requests with totals of 1,020 and 1,060 consume 2,080 tokens in aggregate; the latest request's context approximation is 1,060. Gemini resumed requests report input_tokens_scope="incremental"; their usage does not establish context size. An aggregate or incremental usage record without context_tokens leaves context size unknown.

backend_specific_metadata["provider_usage"] retains the provider's original usage fields, including modality and other token breakdowns. Claude Code also retains model_usage; its primary result usage overlaps that per-model map. Codex preserves thread snapshots and the turn delta separately. These raw records retain provider scopes and are not additional counters to sum.

Read revised and partial usage

Presentational interfaces show usage after a completed turn, using a compact label such as 1,000 input (900 cached), 50 output. The displayed input includes uncached input, cache reads, and separate cache writes; the cached figure counts cache reads within that input. Detailed counters remain available in the data.

Providers emit normalized a11.usage events alongside their raw events. A usage_id identifies one contribution; a higher usage_revision replaces its previous snapshot. An interaction's usage_metadata and an event with the same identity describe the same contribution. Count it once. complete=False marks an unfinished report or a gap in the available source coverage. Missing figures remain unknown, including after a failed or cancelled run.

The gateway stores these observations in the initiating interaction's backend_specific_metadata["a11.usage"]. They travel with the conversation and remain separate from content sent to the model. Read typed observations with a11.sdk.usage.interaction_updates; use UsageLedger to replace revisions when aggregating their consumption. The presentation reducers handle these updates on both the live and replay paths.

Compaction and tool-result clearing preserve earlier consumption. A context_only observation changes the context display without adding tokens to consumption. context_invalidated clears an observation when history changes without a replacement measurement. context_source="reported" identifies a context figure supplied by the harness; "request_estimate" identifies the latest request's input-plus-output approximation. Aggregate usage alone does not establish context occupancy.

For example, requests consuming 1,000 and 700 tokens still consume 1,700 after history is compacted. A harness may separately report a new context of 300 tokens. Include any reported summarization work once, checking whether the harness's aggregate already includes it. Tool output removed before a model request contributes no input to that request; bytes removed from a tool result do not establish an exact token saving.

Reconcile provider and agent scopes

Use UsageLedger when consuming updates directly. It replaces older revisions and excludes rows whose contribution is "reconciliation". These rows retain overlapping detail for inspection; their enclosing aggregate supplies consumption. Each update's scope identifies exposed session, turn, request, and agent IDs. parent_agent_id distinguishes a child's context from the primary context. The figures map retains a value and its reported, partial, or unknown quality for each counter. Unknown output does not erase observed input after a crash.

from a11.sdk.usage import UsageLedger, interaction_updates

ledger = UsageLedger()
for update in interaction_updates(question):
    ledger.observe(update)
usage = ledger.totals()
Provider Consumption source History and interruption behavior
GPT Terminal Responses or Chat Completions usage Keep available terminal counts on incomplete or failed responses; missing terminal usage remains unknown.
Claude All reported usage.iterations, or top-level usage when iterations are absent Compaction iterations contribute once. Context edits preserve consumption and replace context observations.
Codex A delta of each thread's cumulative snapshots Primary and child threads contribute separately. Child completion leaves the parent running. Missing baselines and counter regressions mark incomplete coverage.
Claude Code The inclusive per-model result map, or main-loop usage when that map is absent Result usage survives errors. Observed request inputs survive a missing result; placeholder output stays unknown.
Gemini Interactions usage, including separate thought output Continuation input can be incremental; it does not establish full context occupancy.
Ollama Terminal prompt and evaluation counts Cache and context-shift detail is available only when the daemon exposes it.
vLLM Terminal server usage Prefix-cache, reasoning, speculative, and modality details depend on the server's reporting.
Browser Gemma Optional GemmaEngine.usage() inference counters Counts include generated text removed by stop filtering and are read before teardown on success or failure. The default MediaPipe engine lacks output-token usage counters, so exact consumption is unavailable.

Claude Code's aggregate lifecycle depends on its CLI version. Through 2.1.276, SDK-resumed processes start usage at zero. From 2.1.277, normal session resume and fork restore earlier totals. A11 subtracts the persisted source baseline for that session; an absent baseline or unknown CLI version marks coverage incomplete. Within a streaming query, later results replace the same aggregate. See the Agent SDK usage contract.

Claude API compaction excludes summarization from top-level input and output. A11 sums the iteration records and uses the final iteration separately for a request-context estimate. It does not add top-level usage to those iterations. Enable API history transformations explicitly through betas and context_management in CreateMessageConfig; usage tracking enables no policy by itself. See compaction usage.

Provider streams close when a run completes, fails, or is cancelled. Reported usage already stored with the initiating interaction survives that termination. Unreported work from an interrupted request or an SDK-internal retry remains unknown; visible text, tool-output bytes, and configured context capacity cannot supply an exact replacement measurement.