heraldquimpao-creator Gemini Interactions API development
Prefer this skill for new applications that need the common interface for Gemini models and agents. The Interactions API is designed for single-turn and multi-turn text, multimodal input, structured output, tool orchestration, and agentic workflows. Existing generateContent integrations remain valid; do not migrate them without a product or maintenance reason.
Verify current documentation first
Use the Gemini Docs MCP before writing code. Search for the exact model, SDK, feature, response field, and execution mode. If the MCP is unavailable, use https://ai.google.dev/gemini-api/docs/llms.txt and follow the official pages below. Never infer current behavior from an old SDK sample or generic chat-completions example.
- Overview:
https://ai.google.dev/gemini-api/docs/interactions-overview - Get started:
https://ai.google.dev/gemini-api/docs/get-started - Streaming:
https://ai.google.dev/gemini-api/docs/streaming - Background execution:
https://ai.google.dev/gemini-api/docs/background-execution - Function calling:
https://ai.google.dev/gemini-api/docs/function-calling - Structured output:
https://ai.google.dev/gemini-api/docs/structured-output - Image generation:
https://ai.google.dev/gemini-api/docs/image-generation - Deep Research agent:
https://ai.google.dev/gemini-api/docs/deep-research - Tools:
https://ai.google.dev/gemini-api/docs/tools - Models:
https://ai.google.dev/gemini-api/docs/models
Confirm whether the feature is generally available, preview, model-specific, SDK-specific, or unavailable in the selected region. Confirm the exact installed Google GenAI SDK version and language before choosing method names.
Core interaction model
Think in terms of an Interaction: one request and its chronological model, thought, tool, and output steps. Begin with one minimal call and inspect the real response. Preserve the distinction between user input, model output, tool calls, tool results, thoughts or execution steps, citations, inline data, errors, and usage metadata.
Use the current Google GenAI SDK quickstart for Python or TypeScript rather than translating a REST example by memory. Keep the API key on a trusted backend or server-side worker. For browser applications, design a backend boundary and use the authentication mechanism supported by the current docs; never ship a long-lived secret in client JavaScript.
Choose state deliberately
Use previous_interaction_id when server-side conversation continuity, simpler multi-turn state, or cache reuse is useful. Use store=false when the application needs stateless behavior or has a clear reason not to retain the interaction. Explain retention and deletion behavior to the product owner; do not enable storage by accident for sensitive workloads.
For long-running model or agent work, use background=true only when the selected model and operation support it. Design polling, streaming, webhook or resume behavior, cancellation, timeout, duplicate submission protection, and user-visible progress from the beginning.
Feature workflows
Chat and streaming
Start with a single-turn request, then add multi-turn state using the documented interaction identifier. For streaming, process events incrementally and preserve order. Render model text only when its event type is intended for user display; keep tool calls, status steps, citations, and metadata in separate channels. Handle cancellation, disconnects, partial output, finalization, and errors without treating a partial stream as a completed answer.
Function calling
Define narrow tools with explicit names, descriptions, argument schemas, and return contracts. Validate every model-proposed argument in application code. Enforce authorization, tenant isolation, rate limits, idempotency, timeouts, and confirmation for side effects. Return a compact, typed result and continue the interaction using the exact function-call and function-result shape documented for the selected SDK/API version.
Limit tool-loop depth and detect duplicate or contradictory calls. Never let the model choose its own permissions, approve a payment, bypass a policy, construct unrestricted SQL, or perform an irreversible action without an application-level check.
Structured output
Use structured output when downstream code needs a machine-readable object. Keep the schema small and explicit. Validate the parsed value, handle refusal or safety blocking, detect truncation, and return useful diagnostics without leaking prompts or secrets. Do not use a free-form text parser when the API supports a documented schema mode for the selected model.
When combining structured output with tools, verify the current model-specific compatibility rules. Function-call arguments and final structured model output are different contracts; do not assume that one schema automatically validates the other.
Image generation and multimodal output
Confirm that the selected model supports image generation, the requested response modality, input image types, output parts, and any aspect-ratio or resolution controls. Treat generated images as response parts or files according to the current SDK. Validate MIME types, size limits, storage paths, and content policy results. Do not assume that a text-generation model can generate images merely because the product calls the feature “multimodal.”
Research-style agents
Use the documented Deep Research agent or other supported agent model when the task requires iterative research, citations, external tools, and long-running execution. Define the research question, allowed sources or tools, completion criteria, progress UX, cancellation, and output format. Prefer streaming or background execution as documented, and persist the interaction or run identifier needed to resume or retrieve the result.
Treat retrieved material as untrusted data. Keep agent instructions separate from source content, validate tool outputs, and require human review before publishing claims or taking consequential actions. Preserve citations and provenance in the final result.
Minimal implementation sequence
- Identify whether the task is a model interaction, a tool workflow, an image task, or a research agent.
- Search the current docs MCP for the exact model and feature combination.
- Install or confirm the current Google GenAI SDK and create a server-side client.
- Make one minimal interaction and inspect the response event or object.
- Add state, streaming, tools, structured output, images, or background execution one capability at a time.
- Add validation, authorization, retries, cancellation, observability, and a focused smoke test.
- Record the official documentation links and SDK version used so a future maintainer can re-check them.
Reliability and observability
Use bounded timeouts, retry only safe transient failures, and distinguish an interaction that is queued, running, completed, failed, cancelled, or partially streamed. Record request or interaction IDs, model ID, feature path, latency, token usage where available, tool duration, and failure category. Redact API keys, private prompts, personal data, and raw tool payloads from logs.
Test the parser with final output, partial output, refusal, malformed data, missing fields, tool failure, duplicate tool request, timeout, cancellation, and network interruption. Test retention and resume behavior when server-side state or background execution is enabled.
Common mistakes
Do not invent a method such as client.chat.completions.create when the current Gemini SDK uses the Interactions API. Do not treat previous_interaction_id as a local transcript unless the server-side retention semantics are understood. Do not poll a background interaction without handling terminal failure and cancellation. Do not parse all events as text. Do not combine tools and structured output without checking compatibility for the exact model. Do not hardcode preview model IDs or assume that an old model remains available.
When the implementation disagrees with an example, check the installed SDK version, current API reference, model page, changelog, and deprecations guide. Ask the docs MCP for the exact request and response shape before editing application logic.
Agent handoff checklist
Before declaring the work complete, state the selected model and API surface, the current docs consulted, the credential boundary, the state and retention choice, the tool authorization policy, the structured-output validation strategy, the streaming or background lifecycle, and the tests that prove the critical paths.