Google’s Gemini platform now has a primary API for both models and agents. The Interactions API reached general availability in June 2026 after a public beta that began in December 2025, giving developers one endpoint for ordinary inference, multimodal work, tool orchestration, and long-running agents.

The change is more than a renamed request format. Interactions treats a model run as an observable object with optional server-side state, background execution, tool steps, and a stable identity that can be retrieved or continued. A request can name a Gemini model for inference or an agent for autonomous work without forcing the application to adopt two unrelated integration patterns.

Google recommends Interactions for new projects and says future multimodal, tool, model, and agent capabilities will launch there. The older generateContent API remains supported, however, so existing applications do not need a rushed migration simply to remain functional.

One endpoint, two execution models

The API accepts either a model or an agent. A model call is the familiar pattern: provide input, optional instructions and tools, and receive generated output. An agent call delegates a broader goal to a specialized or managed agent that may plan, use tools, execute code, and work through several steps.

That shared envelope reduces integration friction. An application can use the same interaction concepts for:

It does not mean every model supports every modality or tool. Capability remains model-specific, and preview agents keep their own maturity status even though the API envelope is GA.

Optional server-side state

An interaction has an ID. By default, Google stores requests so a later call can refer to a previous interaction ID instead of resending the entire conversation. This server-side state can simplify multi-turn applications and improve context-cache reuse.

State is optional. Setting store=false requests stateless behavior. Teams should not treat that flag as a complete privacy policy: uploaded files, connected tools, logging settings, cloud projects, and external services may have separate retention rules.

Server-side state is useful when:

It is less appropriate when an application already has a strict event store, must minimize provider-side persistence, or needs deterministic replay from its own records. In those cases, stateless requests can preserve a clearer source of truth.

Background execution for long work

Setting background=true lets the server run an interaction asynchronously and return an ID immediately. The client can poll, stream progress, or reconnect later. This avoids holding one fragile connection open while an agent researches, writes files, executes code, or waits on tools.

Background mode is an execution primitive, not a workflow guarantee. Applications still need:

  1. a durable record of the interaction ID;
  2. timeout and cancellation policies;
  3. bounded polling or webhooks where appropriate;
  4. idempotency around any external write;
  5. user-visible status and error messages;
  6. a way to distinguish retriable failure from final failure.

Google’s July Managed Agents update adds background tasks, remote MCP servers, custom functions, and credential refresh. Those managed-agent capabilities remain distinct from the GA status of the Interactions schema itself.

Observable steps and tool orchestration

Interactions can expose execution steps for debugging and user interfaces. That is valuable for agent products because the final answer often hides the real failure. A poor result may come from the wrong tool, an expired credential, incomplete input, or a model judgment after correct retrieval.

The API can combine built-in tools such as Google Search or Maps with developer functions. Managed agents can also connect to remote MCP servers. Custom functions can move the interaction into a requires-action state so the client executes local business logic and returns the result.

Observability should be designed for different audiences:

Showing every internal event is not automatically transparency. Useful observability explains what happened, which external systems were touched, and what remains unverified.

Google introduced Managed Agents in May 2026. The Antigravity agent runs inside an isolated, ephemeral Linux environment and can reason, execute code, manage files, and browse the web. Developers can define custom agents using versionable instruction and skill files.

The Interactions API can call these agents through the same endpoint as a model. That convenience does not turn the agent into a GA product. Antigravity and managed-agent features have their own preview labels, quotas, regional support, and operational constraints.

This distinction matters for architecture. Keep agent-specific code behind a thin adapter, store important artifacts outside a preview sandbox, and plan for schema or behavior changes.

Cost is still driven by the selected capability

The Interactions API is an interface, not a flat-priced model. Cost depends on the Gemini model, input and output tokens, generated media, built-in tools, managed environments, storage, and external systems used by the interaction.

Server-side state may improve cache hit rates in multi-turn work, but a long stateful thread can also accumulate irrelevant context. Measure accepted task cost rather than comparing request counts. Record model usage, tool calls, background duration, retries, and human review.

For predictable workloads, periodically compact or summarize the state in a controlled way. Preserve source identifiers and decisions; do not let a convenient server-side thread become the only audit record.

Should existing applications migrate?

New projects should normally start with Interactions because Google has designated it as the primary surface for future capabilities. Existing generateContent systems should migrate when they need state, agents, background execution, or the newer tool model.

A safe migration:

  1. inventory current models, tools, safety settings, and streaming behavior;
  2. map request and response fields with Google’s migration guide;
  3. test multi-turn state and stateless mode separately;
  4. compare output quality, latency, token use, and error handling;
  5. run both paths behind a feature flag;
  6. preserve a rollback until production traces are stable.

Do not combine an API migration with a model change and a tool redesign in one unmeasured release. Separate variables make failures easier to diagnose.

From an interaction to a production media workflow

The Interactions API can coordinate a media project, but its interaction ID should not replace the task ID of an external media service. The two objects describe different state machines.

Suppose a Gemini agent reviews a brief and decides that an approved video needs a replacement audio track. The interaction records the conversation, planning, and tool steps. Codex or Claude may then call a separate service such as Medux to upload the approved inputs and create the media job. Medux is not a native Gemini component; it remains an external processing layer.

The Codex MCP video-editing tutorial demonstrates the concrete media lifecycle: inspect local files, request signed upload locations, upload the assets, create an asynchronous task, poll status, and download the output.

Production software should store a mapping such as:

If the Gemini interaction is retried, the controller first checks whether a Medux task already exists. If the media job fails, that failure is returned to the agent as structured evidence rather than starting a duplicate automatically. Keeping conversational state and media-job state separate preserves auditability, prevents double charges, and makes either provider replaceable.