Agent and MCP guides ยท 2026-05-26

What is the Gemini Interactions API? From generateContent to agent state

Understand the Gemini Interactions API versus generateContent, including previous_interaction_id, store, background jobs, webhook_config, steps, and LLM gateway architecture.

Diagram showing a Gemini Interactions API flow with generateContent, previous_interaction_id, background job, webhook, steps, and LLMTR gateway metering.

What the Gemini Interactions API changes

The Gemini Interactions API moves beyond a one-off prompt-response pattern toward a more stateful interaction model. Instead of only sending text to a model, the application also reasons about interaction steps, previous interaction IDs, and long-running task status.

This surface is not mandatory for every workload. Short classification, summarization, or simple chat can remain on chat/completions or generateContent-style calls. Interactions API becomes more useful when multi-step agents, tool use, or background execution are part of the product.

The key difference from generateContent

In a generateContent-style call, most context management stays client-side: conversation history, tool outputs, and retry behavior are assembled by the application. In the Interactions API, `previous_interaction_id`, `steps`, and `store` become explicit architecture decisions.

That difference matters. Stateless calls are easier to inspect and move between providers; stateful interactions can reduce orchestration code and expose intermediate execution steps for longer tasks.

  • `previous_interaction_id`: connects a follow-up call to an earlier interaction.
  • `store`: affects whether interaction state is retained by the provider.
  • `steps`: separates model output, function calls, and action-required states.
  • `usage`: requires tracking text, thought, and tool-use tokens separately.

Background jobs and webhook design

Agent and research tasks can outlive a normal HTTP request. Fields such as `background` and `webhook_config` are designed for starting work without keeping the client waiting and receiving a completion signal later.

In production, that creates a state machine. Pending task UI, duplicate webhook protection, idempotency, timeout policy, and partial error messages need to be planned before shipping.

  • Expose pending, running, completed, and failed states for long tasks.
  • Process webhook events with signature checks, idempotency, and retry tolerance.
  • Bind background results to the correct user account and access boundary.

Where Managed Agents fit

Managed Agents should be treated as a runtime and orchestration layer on top of the Interactions API. A catalog model describes model capabilities and pricing; a managed agent runs that model with tools, sandbox state, files, and follow-up calls.

Cost can therefore include more than input and output tokens. Thought tokens, tool-use tokens, retries, background execution, and runtime boundaries should be measured separately.

How this maps to LLMTR

In a multi-provider gateway such as LLMTR, Interactions API support is not just a direct proxy decision. First decide which workloads stay on the OpenAI-compatible chat surface, which need a provider-native agent API, and which capability labels users should see.

The boundary should be tied to API keys, spending limits, usage metering, and safe error format. Provider keys must stay server-side, and every agent runtime needs a clear cost and metrics policy.

Decide when to use the Gemini Interactions API

Separate stateless model calls, stateful interactions, and managed-agent flows for a Gemini integration.

  1. Classify state requirements. Separate one-response classification and summarization tasks from agent tasks that need follow-up calls or file state.
  2. Select interaction fields. Use `previous_interaction_id`, `store`, `background`, `webhook_config`, and `steps` only when the workload requires them.
  3. Connect gateway metering. Record token, thought-token, tool-use, retry, and latency metrics alongside user flow and API key boundaries.
  4. Close security boundaries. Keep provider keys server-side, avoid persisting prompt bodies in usage records, and make webhook processing idempotent.

Frequently asked questions

Does the Gemini Interactions API replace chat completions?

No. Short stateless tasks may be simpler on chat/completions or generateContent-style calls. Interactions API is worth evaluating when state, background tasks, tool use, or managed agents are part of the workflow.

Does previous_interaction_id mean prompts must be stored?

Provider-side state should be reviewed with the `store` behavior and API policy. For LLMTR usage records, the safer default is to store token, cost, latency, and error metadata without persisting prompt or response bodies.

How should background agent cost be tracked?

Initial requests, follow-up calls, tool use, thought tokens, retries, and webhook completion should be tied to the same user flow. Looking only at final answer tokens undercounts real cost.

Related posts