Planning Agent

Create research plans based on user questions and state

The Planning Agent generates research plans by deciding which tasks to execute (LITERATURE or ANALYSIS) based on the user’s question, available datasets, and current research context.

Function Signature

// src/agents/planning/index.ts
export async function planningAgent(input: {
  state: State;
  conversationState: ConversationState;
  message: Message;
  mode?: PlanningMode;
  usageType?: TokenUsageType;
  researchMode?: ResearchMode;
}): Promise<PlanningResult>;

type PlanningMode = "initial" | "next";
type ResearchMode = "semi-autonomous" | "fully-autonomous" | "steering";

type PlanningResult = {
  currentObjective: string;
  plan: Array<PlanTask>;
};

Planning Modes

Initial Mode

Creates tasks for the current iteration (default, used at start of each message).

const result = await planningAgent({
  state,
  conversationState,
  message,
  mode: "initial",
  usageType: "deep-research"
});

// Returns:
// {
//   currentObjective: "Investigate mechanisms of cellular senescence",
//   plan: [
//     {
//       id: "task-1",
//       type: "LITERATURE",
//       objective: "Search for papers on p53 and cellular senescence",
//       level: "MAX"
//     },
//     {
//       id: "task-2",
//       type: "ANALYSIS",
//       objective: "Analyze expression of senescence markers",
//       datasets: [{ filename: "expression.csv", id: "dataset-1", ... }],
//       level: "MAX"
//     }
//   ]
// }

Next Mode

Updates plan for next iteration after reflection (used after hypothesis + reflection).

const result = await planningAgent({
  state,
  conversationState,
  message,
  mode: "next",
  usageType: "deep-research",
  researchMode: "semi-autonomous"
});

// Generates follow-up tasks based on:
// - Current hypothesis
// - Key insights from reflection
// - Previous task outputs
// - Available datasets

Research Modes

Semi-Autonomous

Default mode. Asks user for approval before each iteration.

planningAgent({
  // ...
  researchMode: "semi-autonomous"
});

The agent generates suggestions but waits for user confirmation.

Fully Autonomous

Continues automatically up to 20 iterations without user input.

planningAgent({
  // ...
  researchMode: "fully-autonomous"
});

Used when user explicitly requests autonomous research.

Steering

User provides specific next steps instead of agent suggestions.

planningAgent({
  // ...
  researchMode: "steering"
});

Agent follows user’s explicit guidance.

Task Types

LITERATURE Tasks

Search scientific literature across configured backends:

{
  "type": "LITERATURE",
  "objective": "Search for recent advances in CRISPR gene editing",
  "level": "MAX"
}

Executed by Literature Agent.

ANALYSIS Tasks

Perform data analysis on uploaded datasets:

{
  "type": "ANALYSIS",
  "objective": "Analyze differential gene expression between treatment groups",
  "datasets": [
    {
      "filename": "expression_matrix.csv",
      "id": "dataset-123",
      "description": "RNA-seq expression data",
      "path": "uploads/expression_matrix.csv"
    }
  ],
  "level": "MAX"
}

Executed by Analysis Agent.

Task Levels

The planning agent assigns priority levels to tasks:

• MAX: High-priority tasks executed in current iteration
• HIGH: Important tasks for future iterations
• MEDIUM: Optional follow-up tasks
• LOW: Nice-to-have explorations

Only MAX level tasks are executed immediately. See Deep Research for details.

Usage Example

// src/routes/chat.ts
const planningResult = await planningAgent({
  state,
  conversationState,
  message,
  mode: "initial",
  usageType: "chat"
});

const plan = planningResult.plan;
const literatureTasks = plan.filter(task => task.type === "LITERATURE");

// Execute only literature tasks in chat mode
for (const task of literatureTasks) {
  const result = await literatureAgent({
    objective: task.objective,
    type: "OPENSCHOLAR"
  });
  task.output = result.output;
}

Configuration

PLANNING_LLM_PROVIDER · string · default: "google"

LLM provider: openai, anthropic, google, or openrouter

PLANNING_LLM_MODEL · string · default: "gemini-2.5-flash"

Model name for planning agent

MAX_AUTO_ITERATIONS · number · default: "5"

Maximum autonomous iterations (semi-autonomous mode)

Prompts

The agent uses different prompts based on context:

Initial planning (no prior plan)

When starting fresh, creates initial literature search plan:

// src/agents/planning/prompts.ts:INITIAL_PLANNING_NO_PLAN_PROMPT

Focuses on understanding the question before diving into analysis.

Initial planning (with prior plan)

When continuing research, considers previous tasks:

// src/agents/planning/prompts.ts:INITIAL_PLANNING_PROMPT

Avoids redundant searches and builds on previous findings.

Next iteration planning

After reflection, plans follow-up tasks:

// src/agents/planning/prompts.ts:NEXT_PLANNING_PROMPT

Incorporates hypothesis, insights, and methodology updates.

Related

Deep Research

Iterative research workflow

Literature Agent

Executes literature tasks

Analysis Agent

Executes analysis tasks