Gemini Workflow Placement: Gems, AI Studio, API, and Vertex AI

Use a Gem for a reusable Gemini workflow

Use a Gem when the workflow should be reused with stable instructions, optional Knowledge files, preview testing, and a dedicated assistant-like setup.

Go to Gems

Use personalization for broad preferences only

Use Instructions for Gemini, Memory, and Connected Apps for broad personalization. Do not use them as the only home for one workflow or one project.

Go to personalization

Prototype model requests and agents in AI Studio

Test prompts, model settings, tools, and structured output. Use Playground's Agents mode to configure and test managed agents.

Go to AI Studio

Use Gemini API / Vertex AI for production systems

Use API or Vertex AI surfaces when the workflow needs system instructions, tools, function calling, Files API, File Search, structured output, RAG, or backend validation.

Go to Gemini API / Vertex AI

Review Gemini tools and advanced capabilities

Use this when the workflow depends on Deep Research, Deep Think, connected apps, retrieval, code execution, function calling, scheduled work, Gems, Spark, or Canvas.

Go to tools and capabilities

Use normal Gemini chat only for one-off tasks

Use ordinary Gemini chat when the task does not need reusable instructions, Knowledge files, API behavior, retrieval, tools, or production validation.

Go to placement rules

Use the API mapping for internal systems

Use the API mapping when Gemini is part of an internal agent, backend service, CI workflow, product feature, retrieval system, or production automation pipeline.

Open API mapping

Gemini app chat: Use for one-off prompts, current questions, current documents, current tasks, or normal chat interaction. Do not use ordinary chat as the only home for reusable workflow rules.
Classic Gems: Custom Gemini assistants for repeated tasks. Use a Gem when you need reusable instructions, a previewable workflow, and optional Knowledge files for recurring work.
Gemini in Chrome Skills: Saved prompts applied to the active browser tab. In Gemini in Chrome, enter /, choose Add Skill, and save a name and prompt. Enter / again to select and run the skill.
Gems from Google Labs: Experimental AI mini-apps powered by Opal. In the Gemini web app, open Gems, then select New Gem beside My Gems from Labs. Describe the workflow and review its generated steps and app preview.
Gem instructions: The instruction layer for a Gem. Use for persona, task, context, format, goals, desired behavior, workflow rules, output requirements, and verification expectations.
Gem Knowledge files: The reference layer for a Gem. Use Knowledge files for reusable source material such as policies, procedures, examples, documents, Drive files, and NotebookLM notebooks where supported.
Instructions for Gemini: Response preferences you explicitly write for supported Gemini chats. These instructions do not apply to Gems; configure a reusable assistant through its own Gem instructions.
Memory: Personalization based on past Gemini chats. Unavailable in Gems and Live chats. Use explicit instructions and reference files for controlled workflows.
Connected Apps: Connections to supported Google and third-party services for retrieving information or performing supported actions. Reusable workflow instructions belong in the relevant instruction layer.
Gemini Spark: Agent workspace with Tasks, Schedules, and Skills. See Spark setup for configuration and custom app connections.
Temporary Chat: Use when the conversation should not appear in Gemini Apps Activity or recent chats. Do not use Temporary Chat as a reusable workflow surface.
Google AI Studio: Developer workspace for testing model requests and configuring agents in Playground. See the AI Studio section below for instruction files, skills, and environment setup.
Managed agents — Public Preview: Gemini API agent runtime hosted by Google. The Antigravity Agent can execute code, manage files, and browse the web in a Linux sandbox.
Gemini API system instructions: Developer instruction layer for API workflows. Use for stable behavior, role, output format, and repeated constraints in application code.
Vertex AI system instructions: Google Cloud surface for production Gemini workflows. Use for system-level behavior on Vertex AI, while keeping sensitive secrets out of prompts and system instructions.
Files API: API file input layer for larger files or files reused across requests. Files are temporary and are not the same as a persistent File Search store.
File Search: Gemini API RAG surface. Use File Search to import, chunk, index, and retrieve relevant source material for model context.
Function calling and tools: Tool/action layer for external APIs, application functions, built-in Google tools, Code Execution, URL Context, Google Search grounding, Google Maps grounding, and Computer Use where supported.
Structured outputs: Output-control surface for JSON/schema-constrained responses used by applications, extraction workflows, UI rendering, validation, or automation.

Where to configure this in Gemini

Create a Gem: In the Gemini web app, open Explore Gems, then select New Gem. Enter a Gem name, add instructions, and save the Gem.
Write Gem instructions: Put stable workflow behavior in the Gem instructions. Google recommends covering persona, task, context, and format when writing Gem instructions.
Use Gemini to rewrite instructions: Use this only as a drafting helper. After Gemini rewrites instructions, manually review scope, behavior, output format, and workflow boundaries before saving.
Add Knowledge files: After adding instructions, use the Knowledge section and select Add files. Add files from device upload, Google Drive, or NotebookLM where supported.
Use Drive files when freshness matters: When a file is added from Drive, Gemini can use the most recent version of the file. Use this only when the workflow should follow the current Drive version.
Use or avoid Knowledge citations intentionally: Use citations for evidence-sensitive workflows. Do not disable Knowledge citations for fact checking, policy review, research review, audit, or any workflow where users need source traceability.
Preview before relying on the Gem: Use the preview text box to test the Gem, then save or update it. Previewing alone does not replace reviewing the instructions and Knowledge behavior.
Edit, delete, pin, or share a Gem: Use the Gem management controls for maintenance and distribution. Management actions do not replace the instruction layer or Knowledge layer.
Verify setup: Ask the Gem to perform a task that requires its instructions and a task that requires its Knowledge files. If behavior is wrong, edit instructions. If source use is wrong, check the Knowledge files and citations.

Where to configure personalization in Gemini

Instructions for Gemini: Open Settings & help → Personal Intelligence → Instructions for Gemini in the Gemini web app to add, edit, delete, or enable instructions. Requires a personal account; work, school, and supervised accounts are excluded. These preferences do not apply to Gems.
Memory: Open Settings & help → Personal Intelligence → Memory. Requires a personal, unsupervised account, age 18+, and Keep Activity enabled. Supported surfaces include Gemini on the web, mobile, Chrome, and smartwatches where available. Memory is unavailable in Gems and Live chats; a text chat can reference a past Live conversation. Correct remembered details in chat; delete conversations containing unwanted information from Gemini Apps Activity.
Connected Apps: Use Connected Apps when Gemini should connect to eligible Google apps to complete requests or personalize responses. Availability can vary by account type, Workspace edition, location, language, device, and app.
Temporary Chat: Use Temporary Chat when the conversation should not appear in Gemini Apps Activity or recent chats. Temporary Chat is not available in every account type or product surface.
Verify setup: Ask Gemini whether it is using broad personalization, then check Personal Intelligence and Connected Apps settings. For workflow-specific behavior, use a Gem or API system instruction instead of personalization.

Where to configure this in AI Studio

Prototype prompts: Use AI Studio to try Gemini models and experiment with prompts. When ready to build, use Get code to move the setup toward Gemini API implementation.
Test chat behavior: Use chat prompts when the workflow requires multi-turn behavior. Keep stable workflow rules separate from current task input when moving from prototype to implementation.
Prototype tools and structured output: Use AI Studio to test supported tool use, structured output, code execution, grounding, or other model/API behavior before implementing it in production code.
Agents Playground: Open Playground and switch to Agents. Start from an Antigravity Agent template, then configure its tools and environment.
Agent instructions: AGENTS.md: Mount .agents/AGENTS.md in the agent environment for stable instructions and persona. The runtime loads this file into the agent's context at startup.
Agent skills: SKILL.md: Place each reusable procedure in .agents/skills/<skill-name>/SKILL.md. The runtime discovers skills in these directories automatically.
Environment sources and settings: Use Environment → Add Sources to supply inline files, Google Cloud Storage sources, or GitHub repositories. Configure sources and network rules before the first message fixes the session configuration.
Verify setup: Confirm that the prompt, model, tool settings, output format, and API code match the intended workflow. For agents, also inspect the mounted files, network rules, generated code, and file changes.

Where to configure Gemini API / Vertex AI workflows

Interactions API

Use Interactions API for new Gemini API projects; generateContent remains supported. When linking turns with previous_interaction_id, resend system_instruction, tools, and generation_config on every request: only conversation history carries over.

System instructions

Put stable behavior rules in system instructions. Use this for role, persona, output format, task rules, formatting requirements, and repeated workflow behavior.

Managed agents and Antigravity Agent

Use the managed runtime when Google should host the agent's execution environment. Supply configuration per interaction, or save it with agents.create and invoke the managed agent by ID. Managed agents remain in Public Preview, independently of the Interactions API's general availability.

Runtime request

Put the current user request, current file, current document, current task, or current constraints in the runtime request. Do not use runtime input as the only home for stable rules.

Thinking controls — Gemini API

In Interactions API model requests, set generation_config.thinking_level. For gemini-3.8-flash, use low to prioritize latency, medium for the default reasoning level, or high for difficult reasoning tasks. minimal is unsupported and returns an error. This API setting is separate from Deep Think in Gemini Apps. Example request body:

{
  "model": "gemini-3.8-flash",
  "input": "Explain the trade-offs between polling and webhooks.",
  "generation_config": {
    "thinking_level": "medium"
  }
}

Generation settings when migrating to Gemini 3.8 Flash

Replace thinking_budget with thinking_level. Remove temperature, top_p, and top_k from generation configuration, and remove unsupported candidate_count. These are the generation-setting changes; consult Google's migration checklist for the remaining requirements.

Deep Research agents — API Preview

Choose an agent version:

deep-research-preview-04-2026 — prioritizes speed and efficiency.
deep-research-max-preview-04-2026 — prioritizes comprehensive research and synthesis.

Invoke through the Interactions API using agent, with background: true and store: true. Put the research brief and report requirements in input; poll or stream progress. Example request body:

{
  "agent": "deep-research-preview-04-2026",
  "input": "Compare cloud database options using vendor documentation and cite the sources.",
  "background": true,
  "store": true
}

Files API

Use the Files API for larger files or files intended for multiple requests. Files API storage is temporary; do not treat it as persistent knowledge storage.

File Search

Use File Search for RAG. File Search imports, chunks, indexes, and retrieves relevant source material to provide context to the model.

Function calling

Use function calling for custom tools that your application executes. Your application receives tool-call JSON, executes the function, and returns the function result to Gemini.

Built-in tools

Use built-in tools when the workflow needs Google Search grounding, Google Maps grounding, URL Context, Code Execution, File Search, or Computer Use where supported.

Structured output

Use structured output when the response must match a JSON/schema-like shape for extraction, UI rendering, validation, or downstream automation.

Vertex AI system instructions

Use Vertex AI system instructions for Google Cloud workflows. Google notes that system instructions guide behavior but do not fully prevent jailbreaks or leaks; do not put sensitive secrets in them.

Verify setup

Test system instructions, runtime requests, tool calls, structured outputs, files, and retrieval separately. Validate outputs outside the model before using them in product, backend, CI, or production workflows.

Capability	Type	Surface	Execution owner	Primary use	Control boundary
Deep Research — Gemini Apps	Search/research mode	Gemini Apps	Gemini-managed research workflow	Plan, search, synthesize, and produce sourced research reports.	Verify source coverage, connected-source access, citations, and plan fit before using the report as evidence.
Deep Research — API	Research agent	Gemini API	Interactions API	Run research with Deep Research or Deep Research Max. See agent configuration.	Preview; requires background execution. Not available through generateContent; structured outputs are unsupported.
Deep Think — Gemini Apps	Reasoning mode	Gemini Apps where available	Gemini-managed reasoning mode	Use extended reasoning for complex planning, analysis, or problem solving.	Do not treat longer reasoning as automatic correctness; verify outputs against supplied evidence and task constraints.
Thinking level — API	Model generation setting	Gemini API	Interactions API generation_config	Configure reasoning effort per request. See thinking controls.	Supported values and defaults depend on the model.
File upload and file analysis	File/data capability	Gemini Apps	Gemini app surface	Analyze uploaded documents, spreadsheets, images, videos, notebooks, or code folders.	Keep uploaded files separate from reusable knowledge; verify document scope and source freshness.
Connected Apps	Connected app layer	Gemini Apps	User-authorized Google or third-party service	Use Gmail, Drive, Docs, Calendar, Maps, YouTube, GitHub, device, or Workspace context where available.	Confirm account, plan, region, app permissions, and whether the action reads data or changes external state.
Classic Gems and custom instructions	Reusable configuration	Gemini Apps	Gemini app configuration	Create reusable assistants, stable behavior instructions, or repeated task setups.	Use for stable task behavior, not for secrets, one-off evidence, or runtime-only constraints.
Chrome Skills	Reusable browser prompts	Gemini in Chrome	Gemini in Chrome	Apply saved instructions to the active tab.	Check tab context, supported language, and account eligibility.
Gems from Google Labs	AI mini-app workflows	Gemini web app	Opal	Create interactive apps with editable workflow steps.	Experimental; creation and editing require a computer. Review steps and outputs.
Canvas	Workspace surface	Gemini Apps	Gemini workspace surface	Create and revise documents, apps, drafts, or structured outputs in an editable workspace.	Do not treat Canvas output as source material; review generated content before publishing or implementation.
Scheduled actions in chat	Scheduled prompts	Gemini chat	Gemini Apps	Prepare recurring responses for scheduled delivery.	Managed separately from Spark schedules.
Spark tasks	Task execution	Gemini Spark	Spark and connected services	Define and carry out a goal across multiple steps.	Review progress, outputs, and external actions.
Spark schedules	Task triggers	Gemini Spark	Spark scheduler	Start tasks at configured times or supported events.	Execution timing is approximate; monitors are unsuitable for time-critical work.
Spark skills	Reusable instructions and context	Gemini Spark	Spark instruction configuration	Define procedures that can be reused across tasks.	Keep reusable procedures separate from individual task inputs.
Custom Connected Apps via MCP	External tools and data	Gemini Spark and chat, where available	Connected service / MCP server	Access a custom app through its MCP server URL.	Distinguish retrieval from operations that modify external data.
Google Search and Google Maps grounding	Platform-managed tool	Gemini API / Vertex AI where supported	Google-managed tool execution	Ground responses in web or location/map context.	Verify grounding metadata, source provenance, model support, and whether the selected surface supports the tool.
URL Context and File Search	Retrieval/source capability	Gemini API / Vertex AI where supported	Google-managed retrieval	Retrieve context from URLs or indexed files for RAG-style workflows.	Verify retrieved context, indexed source set, chunking assumptions, and whether retrieval actually supports the claim.
Code Execution and Computer Use	Execution tool	Gemini API where supported	Google-managed or client-controlled execution boundary, depending on tool	Run code-backed computation or operate a browser/computer environment where supported.	Validate outputs, inspect side effects, and require approval for external, destructive, or user-visible actions.
Function Calling	Application-owned tool call	Gemini API / AI Studio prototype	Application-owned execution	Let the model request custom functions, APIs, database lookups, or business-system actions.	Validate schema, arguments, permissions, side effects, and returned results outside the model.
Live API and media generation	Agentic / media capability	Gemini API / Gemini Apps where available	Gemini-managed generation or realtime interaction surface	Build realtime voice/vision experiences, generate images, or use media workflows where supported.	Verify availability, model support, safety requirements, and whether generated media needs review before use.

Spark setup: tasks, schedules, skills, and connections

Tasks: the current goal: Open Switch to Spark → Tasks. Describe the outcome you want Spark to deliver and provide the current task's inputs.
Schedules: when a task runs: Set a schedule in a task thread, or use Schedules → Create manually for a time-based schedule. Supported triggers include time, Gmail filters, and topic monitors. Gemini chat's Scheduled actions are a separate feature.
Skills: reusable procedures: Open Skills to define a name, description, and instructions. Enabled skills can be selected automatically when relevant; enter / in a task thread to select one explicitly.
Import a skill: Use Skills → Upload with a SKILL.md file or a ZIP containing SKILL.md at its root. Uploaded skill scripts cannot make external network requests.
Custom app connections: In the Gemini web app, open Settings → Connected Apps → Custom apps and enter the app's MCP server URL. If needed, open Personal Intelligence first to find Connected Apps. Custom apps currently require a personal account, age 18+, US location, English, and Keep Activity enabled.
Connected information and external actions: Retrieved information supplies task context; write tools can change data in the connected service. Google currently requires manual confirmation for custom-app write actions.

Verification checklist

Verify the capability exists on the selected Gemini surface, model, plan, account, and region.
Separate Gemini-managed tools from application-owned function calls.
Verify connected-app permissions before relying on Gmail, Drive, Calendar, GitHub, or Workspace data.
Verify source provenance for Deep Research, grounding, URL Context, and File Search outputs.
Require validation and approval before external, user-visible, destructive, or irreversible actions.
Do not use tools, Canvas, Gems, Spark skills, or custom instructions as a substitute for stable source material or policy enforcement.

Workflow layer	What belongs here	Best Gemini placement	Do not use for
Instruction layer	Role, task rules, response format, and verification requirements intended to apply across tasks.	Classic Gem instructions, Chrome Skill prompts, Spark skill instructions, Gemini API system instructions, Agent Platform system instructions, or `.agents/AGENTS.md` for managed agents. Use Instructions for Gemini only for broad personalization.	Source files, secrets, one-off input, temporary notes, or mutable business state.
Reference / source material layer	Policies, examples, docs, Drive files, notebooks, source documents, research packs.	Gem Knowledge files, Files API, File Search stores, URL Context, app-owned retrieval, or Drive-connected sources where supported.	Behavior rules that must always apply; those belong in the instruction layer.
Reusable workflow layer	Repeatable assistant behavior, recurring tasks, reusable procedures, stable response formats.	Classic Gems for reusable assistants; Chrome Skills for saved browser prompts; Gems from Google Labs for AI mini-app workflows; Spark skills for reusable procedures; API orchestration for products/internal systems; `.agents/skills/<skill-name>/SKILL.md` for managed-agent procedures.	One-off chat prompts that must be manually reconstructed every time.
Runtime prompt layer	The current question, current file, current document, current task, current constraints.	Gemini app chat, Gem chat prompt, API request contents, AI Studio prompt.	Permanent workflow policy, source governance, credentials, or long-lived reference material.
Tool / retrieval layer	External functions, built-in tools, search grounding, URL retrieval, code execution, RAG, app data.	Function calling, built-in tools, File Search, Google Search grounding, URL Context, Google Maps, Code Execution, Connected Apps.	Unvalidated writes, sensitive operations, or production side effects without application-side controls.
Personalization layer	Broad preferences, past-chat personalization, connected app personalization.	Instructions for Gemini, Memory, Connected Apps settings.	Formal verification, project memory, deterministic workflow control, or source-of-truth storage.
Verification layer	Source checks, schema checks, citation checks, policy checks, output acceptance criteria.	Gem instructions, API validation layer, structured output validation, application-side evals, final verification prompt.	Informal “looks good” review for publication, client delivery, production use, or automated actions.

If the workflow is one-off: Put the current task in Gemini app chat or the current API request. Do not create a Gem unless the workflow will recur.
If the workflow should repeat: Use a classic Gem for a reusable assistant with instructions and Knowledge files, Chrome Skills for saved prompts applied to browser pages, or Gems from Google Labs for an interactive AI mini-app powered by Opal. In Spark, put reusable procedures in Skills and the current goal in a Task. Add a Schedule when the task should start automatically.
If the rule should apply broadly across Gemini chats: Use Instructions for Gemini only for broad preferences. Do not put one project or one procedural workflow there.
If source material should be reused: Use Gem Knowledge files, Drive-connected files, File Search, Files API, URL Context, or application-owned retrieval depending on the surface.
If the workflow is developer-facing: Prototype model requests or agents in Google AI Studio. Use API system instructions for model integrations; use the managed-agent configuration and environment files for workflows built on Antigravity Agent.
If the workflow needs tools: Use built-in tools or function calling. Keep tool execution and side effects under application-side validation and permission controls.

Do not put reusable workflow rules only in ordinary Gemini chat if the workflow should repeat.
Do not put large reusable source material in the prompt when it belongs in Gem Knowledge, File Search, Files API, URL Context, or retrieval.
Do not use Instructions for Gemini as the home for one project-specific or workflow-specific procedure.
Do not treat Memory or Connected Apps as deterministic workflow control.
Do not disable Knowledge citations for evidence-sensitive workflows.
Do not put secrets, API keys, credentials, private tokens, or privileged environment values in Gem instructions, Knowledge files, prompts, or system instructions.
Do not rely on system instructions as a complete security boundary. Use application-side authorization, validation, logging, and evals.
Do not assume a capability is available to every user or model. Account type, Workspace settings, region, language, product surface, model, and rollout state can affect availability.

Gemini Workflow Placement: Gems, AI Studio, API, and Vertex AI

Start with the workflow layer, then choose the Gemini surface

Gemini setup decision

Use a Gem for a reusable Gemini workflow

Use personalization for broad preferences only

Prototype model requests and agents in AI Studio

Use Gemini API / Vertex AI for production systems

Review Gemini tools and advanced capabilities

Use normal Gemini chat only for one-off tasks

Use the API mapping for internal systems

Primary surfaces

Gems

Where to configure this in Gemini

Personalization

Where to configure personalization in Gemini

Google AI Studio

Where to configure this in AI Studio

Gemini API / Vertex AI

Where to configure Gemini API / Vertex AI workflows

Map Gemini capabilities by surface, execution owner, and control boundary

Spark setup: tasks, schedules, skills, and connections

Verification checklist

Layer placement map

Placement rules

Misplacement guardrails

Official source check

Next steps