Skip to main content

Deep Agents

Deep agents are AI systems that execute extended, multi-step workflows autonomously. They maintain persistent memory, decompose objectives into sub-tasks, delegate to specialized sub-agents, and coordinate via shared artifacts. They checkpoint progress, manage token budgets through compaction, and iterate until the end goal is reached.

Sub-Agent Delegation​

Agents declare sub-agents in their TOML frontmatter:

name = "deepresearch"
sub_agents = ["coder"]
max_iterations = 40

[tools]
builtin = ["transfer_to_agent", "todos", "artifact"]

At runtime, the parent agent uses the transfer_to_agent tool to delegate work to a child. The child agent gets an isolated context — its own task_id, run_id, and token budget — but shares the same thread for continuity. When the child completes, control returns to the parent with a summary of results.

This lets you compose specialized agents. A research agent handles planning and synthesis while delegating data collection, code execution, and web scraping to a coder agent that has the right tools for those jobs.

Skills as On-Demand Knowledge​

The load_skill tool loads domain-specific instructions into an agent's context on demand, without requiring them at startup.

Inline mode (default): The skill's markdown content is injected directly into the agent's conversation. The ActiveSkillTracker preserves loaded skills so they survive context compaction — if compaction drops older entries, skills are automatically re-injected.

Fork mode: Spawns an isolated child agent with the skill content as its instruction set. The child runs with its own token budget and returns a summary to the parent. The parent-child relationship is persisted via parent_task_id.

Agents can declare which skills they have access to:

[[available_skills]]
id = "*"
name = "*"

Remote Execution (Sandboxing)​

The --remote flag runs an agent in an isolated browsr container with a full toolkit (Python, Node.js, shell). This is useful for untrusted code execution, resource isolation, or when the agent needs to install dependencies without affecting the host.

distri run coder --task "Analyze this dataset" --remote

Events stream back from the container via SSE, so you get real-time visibility into what the agent is doing.

Context Management​

ContextSizeManager handles token budgets through a tiered compaction system:

  • Tier 1 (60% usage): Mechanical trimming — drops older scratchpad entries while preserving the user task and minimum context.
  • Tier 2 (80% usage): Semantic compaction — summarizes older entries using an LLM call, condensing history into a compact summary.
  • Tier 3 (95% usage): Emergency reset — aggressive compaction to recover from near-overflow.

After any compaction, the ActiveSkillTracker re-injects loaded skill content (up to 25K tokens) so the agent does not lose domain knowledge mid-task.

Agents also use planning and re-planning strategies to structure multi-step work, and persist state to threads so they can checkpoint and resume.

Built-in Deep Agent: deepresearch​

Distri ships with a deepresearch agent that demonstrates these patterns:

distri run deepresearch --task "Research the current state of quantum computing"

Key features:

  • Sub-agents: Delegates to coder for web search, scraping, shell execution, and data processing.
  • TODO-driven tracking: Creates and manages TODOs to track research progress, mark items in-progress or done, and discover new angles.
  • Multi-phase workflow:
    1. Landscape mapping — broad search to identify sources, domains, and knowledge gaps.
    2. Deep-dive — systematic investigation of each area, delegating to coder for data collection, with findings saved as artifacts.
    3. Synthesis — cross-reference findings, fact-check claims, run final analysis, and produce a comprehensive report with citations.
  • 120K token context with deep reasoning enabled for thorough analysis.