Deep Research Collaborative Planning (Interactions)

Human-in-the-loop research: the agent proposes a plan, you refine it, then approve it to run the full research.

The flow chains turns through previous_interaction_id:

collaborative_planning=True → agent returns a research plan.
collaborative_planning=True → refine the plan (optional).
collaborative_planning=False → agent executes the approved plan.

collaborative_planning is read fresh on every request, so flipping it on the model between turns switches plan-mode to execute-mode within the same conversation.

Code

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.models.google import GeminiInteractions
4
5agent = Agent(
6    model=GeminiInteractions(
7        agent="deep-research-preview-04-2026",
8        collaborative_planning=True,
9        thinking_summaries="auto",
10        agent_poll_interval=5.0,
11    ),
12    add_history_to_context=True,
13    db=SqliteDb(db_file="tmp/deep_research_collab.db"),
14    markdown=True,
15)
16
17SESSION_ID = "deep-research-collab-1"
18
19if __name__ == "__main__":
20    agent.print_response(
21        "Do some research on Google TPUs.",
22        session_id=SESSION_ID,
23    )
24
25    agent.print_response(
26        "Focus more on the differences between Google TPUs and competitor "
27        "hardware, and less on the history.",
28        session_id=SESSION_ID,
29    )
30
31    agent.model.collaborative_planning = False
32    agent.print_response(
33        "Plan looks good!",
34        session_id=SESSION_ID,
35    )

Note

Mutating agent.model.collaborative_planning mid-conversation is safe only when the model instance is not shared across concurrent runs. For concurrent use, prefer two separate agents (a planner and an executor) sharing a session.

Usage

Set up your virtual environment

1uv venv --python 3.12
2source .venv/bin/activate

1uv venv --python 3.12
2.venv\Scripts\activate

Set your API key

1export GOOGLE_API_KEY=xxx

Install dependencies

1uv pip install -U "google-genai>=2.0" kern-ai

Run Agent

1python cookbook/90_models/google/gemini_interactions/deep_research_collaborative_planning.py