Dify Agent Monorepo Structure#

Overview#

dify-agent is a standalone subpackage within the Dify monorepo, introduced in PR #36087. It implements Agent V2 — an async microservice model replacing the legacy synchronous BaseAgentRunner stack — and lives at dify-agent/ under the repo root 1.

The package runs as a FastAPI server (dify_agent.server.app:app) backed by Redis Streams for event persistence, and communicates with the Dify Plugin Daemon for LLM calls 2.

Source Namespaces#

The src/ directory 3 contains four top-level packages, all installed from a single pyproject.toml 4:

Key subdirectories within dify_agent/#

Full directory tree with file-level descriptions: 1

Dependency Management (pyproject.toml + uv)#

dify-agent ships its own pyproject.toml and a checked-in uv.lock, making it independently buildable without the api/ project.

Base dependencies (always installed) 5:

• httpx, httpx2 — HTTP client transport
• pydantic, pydantic-ai-harness>=0.20.0,<0.21.0, pydantic-ai-slim>=2.30.0,<3.0.0 — data validation, LLM agent runtime, and history compaction
• typing-extensions

Optional extras 6:

Dev toolchain is in the [dependency-groups] dev group 7: pyrefly, ruff, pytest, coverage.

Type checking is configured via [tool.pyrefly]:

• project-includes = ["src", "examples"] — check source and examples only
• project-excludes = [".venv", "tests/"] — skip tests
• search-path resolves imports from src, examples/agenton, and examples/dify_agent
• python-platform = "linux", python-version = "3.12.0"

Run via make typecheck → pyrefly check with --group dev --extra server.

Install all extras for local development:

cd dify-agent && uv sync --all-extras --all-groups

Docker Image: dify-agent-backend#

The dify-agent/Dockerfile uses a three-stage multi-stage build targeting python:3.12-slim-trixie:

Stage 1 – base 8: Installs uv (pinned to 0.8.9) via pip. Shared by both subsequent stages.

Stage 2 – packages 9: Copies dify-agent/pyproject.toml, uv.lock, README.md, and src/ from the repo root build context, then runs:

uv sync --frozen --no-dev --no-editable --extra server

--frozen trusts the checked-in lock for reproducible builds; --no-editable bakes source into site-packages.

Stage 3 – production 10:

• Sets locale/encoding environment variables
• Creates a non-root dify user (uid 1001, matching the dify-api image convention) 11
• Copies the virtualenv from the packages stage into /app/api/.venv
• Pre-creates /app/api/storage (bind-mounted at runtime)
• Exposes port 5050
• Entrypoint: uvicorn dify_agent.server.app:app --host 0.0.0.0 --port 5050 12

The build context is the repository root — not dify-agent/ — so paths in COPY are repo-root-relative 13.

CI/CD#

Four images are published in CI 14:

Each is built in a parallel matrix (one job per platform: linux/amd64, linux/arm64) using Depot runners, pushed by digest, then merged into a multi-platform manifest 14.

Related Entry Points#

See also: Agent V2 Architecture | Agent Runtime Backend Initialization