# How Research Subagents Are Defined and Invoked in Feynman: A Technical Deep Dive

> Discover how Feynman research subagents are defined using markdown and invoked programmatically with Pi's subagent tool for efficient parallel or single task execution.

- Repository: [Advait Paliwal/feynman](https://github.com/advaitpaliwal/feynman)
- Tags: deep-dive
- Published: 2026-09-08

---

**Research subagents in Feynman are defined as markdown-based specifications in `.feynman/agents/` and invoked programmatically via Pi’s `subagent` tool using `runs.all()` for parallel execution or `runs.one()` for single tasks.**

Feynman orchestrates complex research workflows through **bundled Pi subagents**, with the **researcher** subagent serving as the primary autonomous information-gathering component. This architecture enables parallel literature reviews, web searches, and data extraction while maintaining strict orchestration control within the Pi framework. Understanding how these subagents are defined and invoked is essential for extending Feynman’s capabilities or debugging research pipelines.

## Defining Research Subagents in Feynman

The researcher subagent follows a declarative configuration pattern that separates agent capabilities from execution logic.

### The Markdown-Based Agent Specification

Agent definitions reside in the hidden **`.feynman/agents/`** directory as markdown files. The core researcher specification lives at [`website/src/content/docs/agents/researcher.md`](https://github.com/advaitpaliwal/feynman/blob/main/website/src/content/docs/agents/researcher.md), which delineates the agent’s purpose, search strategy, extraction pipeline, and dependent workflows. This file acts as the canonical contract between the orchestration layer and the research implementation.

According to the source, the markdown definition describes how the researcher queries **AlphaXiv** for academic papers, performs web searches for documentation, and interfaces with Hugging Face repositories. The specification includes structured directives that tell the Pi framework which tools to inject—specifically `web_search` and `fetch_content`—when initializing the subagent.

### Loading via the Subagent Extension

At runtime, Pi loads these definitions through the **subagent extension**. The extension’s configuration (located in the `subagents` section of Pi’s main settings) points to the bundled prompts stored in the `.feynman/agents/` directory. Feynman’s setup scripts ensure these prompts are properly registered by patching Pi’s configuration file at `~/.pi/agent/extensions/subagent/config.json`.

The patching logic is implemented in `scripts/lib/pi-subagents-patch.mjs`, which validates that the bundled researcher definition is included in the extension’s load path. This ensures that when workflows invoke `agent: 'researcher'`, Pi can resolve the specification to the correct markdown prompt and inject the appropriate search tools.

## Invoking Research Subagents in Workflows

Workflow scripts invoke the researcher through Pi’s **`subagent` tool**, using either parallel or singular execution patterns depending on the research scope.

### Parallel Execution with runs.all

For comprehensive research tasks requiring multiple information sources, lead agents spawn parallel researcher instances using **`runs.all`**. This method accepts an array of task configurations, each specifying the target agent, task description, and output file path.

The following example from the deep research workflow demonstrates parallel invocation for web and academic sources:

```typescript
await runs.all([
  {
    key: 'web',
    agent: 'researcher',
    task: 'Read outputs/.plans/xyz-T1.md and write xyz-research-web.md.',
    output: 'xyz-research-web.md',
  },
  {
    key: 'papers',
    agent: 'researcher',
    task: 'Read outputs/.plans/xyz-T2.md and write xyz-research-papers.md.',
    output: 'xyz-research-papers.md',
  },
]);

```

Each entry in the array executes concurrently, with the `key` providing a unique identifier for result aggregation. The `task` string is interpreted by the researcher’s prompt logic to determine whether to prioritize AlphaXiv queries, general web searches, or repository mining.

### Single Agent Calls with runs.one

For scoped research tasks, workflows use **`runs.one`** to invoke a single researcher instance. This approach is common in literature review commands or targeted audits where parallelization is unnecessary.

```typescript
await runs.one({
  key: 'lit',
  agent: 'researcher',
  task: 'Gather literature on "graph neural networks".',
  output: 'gnn-literature.md',
});

```

### Task Interpretation and Output Handling

The researcher subagent processes the `task` parameter to determine search strategy and scope. Upon completion, the agent writes structured findings to the path specified in the `output` field. The lead agent validates these output paths before proceeding to downstream processing agents such as the **verifier** or **writer**, ensuring data integrity across the pipeline.

## Configuration and Customization

Users can customize researcher behavior without modifying core prompt files through Pi’s settings override system.

### Agent Overrides in Settings JSON

Configuration overrides reside in the **settings JSON** under `subagents.agentOverrides.researcher`. These overrides allow adjustment of thinking levels, extension permissions, and custom tool injection. The configuration file is read from Pi’s home directory and dynamically patched by Feynman’s initialization scripts to ensure bundled prompts remain the default while user preferences take precedence.

For example, users can restrict the researcher to specific academic databases or enable additional content extraction tools by modifying the `agentOverrides` object before the subagent extension initializes.

## Integration with High-Level Commands

The researcher subagent serves as a required dependency for Feynman’s high-level CLI commands. Commands including `/deepresearch`, `/lit`, `/review`, `/audit`, `/replicate`, `/recipe`, `/compare`, and `/draft` declare the researcher as a mandatory subagent in their workflow definitions.

When these commands execute, the lead agent evaluates topic breadth to determine whether to spawn one or multiple researcher instances. For broad survey tasks, the system automatically parallelizes research across web and academic sources, while narrow technical queries trigger single-agent invocations. This dynamic orchestration ensures optimal resource utilization while maintaining the structured output requirements of each command.

## Summary

- **Research subagents** in Feynman are defined via markdown specifications in [`.feynman/agents/researcher.md`](https://github.com/advaitpaliwal/feynman/blob/main/.feynman/agents/researcher.md), which describe search strategies and tool requirements.
- Pi’s **subagent extension** loads these definitions at runtime and injects tools like `web_search` and `fetch_content` for AlphaXiv and repository queries.
- Workflows invoke researchers using **`runs.all`** for parallel tasks or **`runs.one`** for singular investigations, specifying tasks and output paths in the invocation object.
- High-level commands (`/deepresearch`, `/lit`, etc.) automatically orchestrate researcher subagents based on topic complexity.
- Customization occurs through **`subagents.agentOverrides.researcher`** in Pi’s settings JSON, enabling tool and strategy adjustments without modifying core prompt files.

## Frequently Asked Questions

### Where is the researcher subagent defined in the Feynman repository?

The researcher subagent is defined in [`website/src/content/docs/agents/researcher.md`](https://github.com/advaitpaliwal/feynman/blob/main/website/src/content/docs/agents/researcher.md), which specifies the agent’s purpose, search strategies, and workflow dependencies. This markdown file resides in the hidden `.feynman/agents/` directory structure and is loaded by Pi’s subagent extension at runtime.

### How does Feynman execute multiple research tasks in parallel?

Feynman uses Pi’s **`runs.all`** method to execute researcher subagents concurrently. Workflow scripts pass an array of configuration objects, each containing an `agent: 'researcher'` declaration, a specific `task` string, and an `output` file path. This pattern enables simultaneous web searches and academic paper reviews while maintaining isolated output files for aggregation.

### Can I customize the researcher subagent’s behavior without editing core files?

Yes. Users can override researcher behavior through the **`subagents.agentOverrides.researcher`** section in Pi’s settings JSON located at `~/.pi/agent/extensions/subagent/config.json`. These overrides allow modification of thinking levels, tool availability, and search strategies while preserving the base prompt definitions in the Feynman repository.

### Which Feynman commands rely on the researcher subagent?

The researcher subagent is required for multiple high-level commands including `/deepresearch`, `/lit`, `/review`, `/audit`, `/replicate`, `/recipe`, `/compare`, and `/draft`. Each command implements specific orchestration logic that determines whether to invoke a single researcher instance or parallelize tasks across multiple subagents based on the query scope.