Skip to content

Agent Architecture

DAIV uses a single AI agent built on Deep Agents, a general-purpose deep agent framework from LangChain with sub-agent spawning, middleware-based architecture, and virtual filesystem — all running on LangGraph. This page covers the technical architecture for those who want to understand how DAIV works under the hood.

Overview

DAIV's architecture consists of:

  • One main agent — handles all tasks (issue addressing, code review, slash commands)
  • Built-in subagents — general-purpose (full tools), explore (read-only, fast), and a fan-out of read-only cr-* code-review detector subagents
  • Middleware stack — modular capabilities injected based on configuration
  • MCP servers — external tool integrations (Sentry, Context7)
graph TB
    WH[Webhook Event] --> CB[Callback Handler]
    CB --> TQ[Task Queue]
    JOB[Jobs API] --> TQ
    TQ --> MGR[Manager / Task]
    MGR --> AGENT[DAIV Agent]

    AGENT --> MW[Middleware Stack]
    MW --> FS[Filesystem Tools]
    MW --> GIT[Git Tools]
    MW --> GP[Git Platform Tools]
    MW --> SB[Sandbox]
    MW --> WS[Web Search / Fetch]
    MW --> SK[Skills]
    MW --> SA[Subagents]
    MW --> MCP[MCP Tools]

    SA --> GPAgent[General-Purpose]
    SA --> EXAgent[Explore]
    SA --> CRAgent[Code-Review Detectors cr-*]

    AGENT --> PUB[Git Change Publisher]
    PUB --> COMMIT[Commit & Push]
    PUB --> MR[Create / Update MR]

End-to-end flow

  1. Trigger — a webhook event from GitLab/GitHub, or a Jobs API request
  2. Dispatch — the callback handler (webhooks) or API view (jobs) enqueues a background task
  3. Context setup — the task sets up the runtime context (repository, branch, scope) and creates the agent
  4. Agent execution — LangGraph runs the agent loop: call LLM → execute tools → repeat
  5. Output — the agent commits changes and creates/updates a merge request (webhooks), or the text result is stored for polling (jobs)

Managers

Two managers orchestrate the agent:

Manager Trigger Purpose
IssueAddressorManager Issue with daiv label Plans and implements issue solutions
CommentsAddressorManager @daiv mention on MR Responds to code review comments

Both create a persistent conversation thread (stored in Redis with a 7-day TTL by default, configurable via DJANGO_REDIS_CHECKPOINT_TTL_MINUTES) so the agent retains context across multiple interactions on the same issue or MR.

Tools

The agent's tools are injected via middlewares. Each middleware provides one or more tools and can be conditionally enabled.

Tools are deferred by default

Only a small core (ls, read_file, write_file, edit_file, glob, grep, bash, write_todos, skill, and the task delegation tool) is bound to the model up front. Everything else — web search/fetch, the git platform tool, and all MCP tools — is hidden behind a tool_search capability provided by DeferredToolsMiddleware and loaded on demand. Once loaded, a tool stays available for the rest of the session. This keeps the model's tool list small without giving up access to the full toolset.

Filesystem

Tool Description
glob Find files by pattern matching
grep Search file contents with regex
read_file Read file contents
edit_file Modify existing files
write_file Create new files
ls List directory contents

Git platform

Tool Description
gitlab / gh Inspect issues, merge requests, pipeline status, and job logs (the GitHub tool exposes the gh CLI)

Sandbox

Tool Description
bash Execute commands in a persistent, isolated Docker container

Commands are evaluated against a command policy before execution. See Sandbox for details.

Web

Tool Description
web_search Search the web (DuckDuckGo or Tavily)
web_fetch Fetch a URL, convert to markdown, and answer a prompt about its content

Skills

Tool Description
skill Execute a skill (slash command)

MCP

External tools provided via MCP servers (Sentry error tracking, Context7 documentation lookup).

Middlewares

Middlewares are the backbone of the agent — they inject tools, system prompts, and lifecycle hooks. The agent is assembled dynamically based on which middlewares are enabled.

Always enabled

Middleware Purpose
FilesystemMiddleware File operations (glob, grep, read, edit, write)
GitMiddleware Branch management, auto-commit, MR creation
GitPlatformMiddleware Git platform CLI tool (issues, MRs, pipelines)
SkillsMiddleware Skill loading and slash command execution
SubAgentMiddleware Delegates tasks to subagents
MemoryMiddleware Loads AGENTS.md and repository context
TodoListMiddleware Task tracking within conversations
SummarizationMiddleware Compresses conversation history when it grows too long
AnthropicPromptCachingMiddleware Prompt caching for Anthropic models
ToolCallLoggingMiddleware Logs all tool calls
PatchToolCallsMiddleware Fixes malformed tool calls from the LLM
DeferredToolsMiddleware Defers non-core tools behind a tool_search capability, loaded on demand
LoopBreakerMiddleware Detects verbatim tool-call repetition and finalizes the run (instead of raising) so end-of-run hooks still execute
StepBudgetMiddleware Warns the model as the run approaches its per-run step budget
EnsureResponseMiddleware Guarantees a non-empty final response by retrying empty LLM responses

Conditionally enabled

Middleware Condition
SandboxMiddleware A SandboxEnvironment is resolvable for the run (per-run pick or GLOBAL default exists)
WebSearchMiddleware DAIV_WEB_SEARCH_ENABLED is true
WebFetchMiddleware DAIV_WEB_FETCH_ENABLED is true
ModelFallbackMiddleware A fallback model is configured
SlashCommandMiddleware Slash commands enabled in .daiv.yml (default on) — parses and dispatches /commands like /agents and /help

Subagents

The main agent can delegate work to two general-use subagents. See Subagents for the user-facing explanation.

Subagent Model Fallback Tools Use case
General-purpose Same as main agent Same as main agent Full tool access Complex searches, multi-step research
Explore Claude Haiku 4.5 (fast) GPT-5.4-mini Read-only filesystem Quick file lookups, code structure questions

In addition, a set of read-only code-review detector subagents (cr-correctness, cr-security, cr-performance, cr-structure, cr-custom-rules) is built and registered on every run. The code review skill picks the detectors applicable to the change, fans out across them in parallel, and aggregates their markdown reports into a single review report; each detector runs with a read-only tool stack. Custom subagents defined per repository are also added to the available-agents list.

All subagents (including custom subagents) support automatic model fallback via ModelFallbackMiddleware. When the primary model fails, the subagent retries with the configured fallback model. The general-purpose subagent and custom subagents use the main agent's fallback model; the explore subagent uses its own (DAIV_AGENT_EXPLORE_FALLBACK_MODEL_NAME).

Dynamic system prompt

The agent's system prompt is assembled at runtime and includes:

  • Current date
  • Bot username
  • Repository URL and git platform
  • Current branch and default branch
  • Available tools and their descriptions
  • Loaded skill metadata
  • AGENTS.md content (if present in the repository)

This ensures the agent always has up-to-date context about the repository it's working in.

Model configuration

Models are resolved at three levels (highest priority first):

  1. Issue labels — daiv-max switches to a stronger model with higher thinking
  2. Repository config — .daiv.yml model overrides
  3. Environment variables — global defaults (DAIV_AGENT_*)

See Environment Variables for all agent model settings.