agent-deep-research_skill

Overview

This skill performs asynchronous deep research using the Google Gemini Interactions API without requiring the Gemini CLI. It supports RAG-grounded queries against local files, cost previews, structured JSON outputs, and adaptive polling to manage long-running research sessions. The skill is agent-friendly and designed to integrate with 30+ AI agents for automated workflows.

How this skill works

The skill launches a deep-research interaction via the Gemini Interactions API, optionally creating and uploading an ephemeral file-search store from a local path for RAG grounding. It polls the Gemini service until completion (with adaptive or fixed polling), then writes structured outputs to disk or streams compact JSON for agent consumption. Dry-run mode estimates costs and context upload expenses before starting work.

When to use it

• When you need long-running, multi-step research driven by a deep-research agent.
• To ground answers in local code, docs, or other files using an ephemeral or persistent file search store.
• When integrating research tasks into automated AI agent pipelines that require machine-readable results.
• When you want a cost estimate before committing to a research run.
• When you need structured outputs (report, metadata, full interaction) for downstream processing.

Best practices

• Provide a narrow, specific research question and use --context to ground results in your repo or docs.
• Use --dry-run to preview estimated costs when working with large contexts or long timeouts.
• Save results with --output-dir to receive a compact JSON summary for agent handoffs and full artifacts on disk.
• Enable --smart-sync for uploads to avoid re-sending unchanged files and reduce upload time and cost.
• Keep environment keys in secure runtime secrets and set GEMINI_DEEP_RESEARCH_API_KEY for highest priority.

Example use cases

• Analyze the security architecture of a codebase by auto-creating a file search store from the repo and producing a detailed report.
• Run a non-blocking research job, poll status from an orchestration agent, and fetch the final report when complete.
• Perform quick Q&A against uploaded documentation stores for support bots or knowledge-base assistants.
• Estimate research cost for project budgets before executing long or grounded queries.
• Integrate into CI pipelines to produce structured research artifacts for audits or design reviews.