Glossary

Relevant source files

• api/.env.example
• api/configs/feature/__init__.py
• api/configs/middleware/__init__.py
• api/configs/packaging/__init__.py
• api/controllers/console/agent/composer.py
• api/controllers/console/agent/roster.py
• api/core/rag/datasource/vdb/vector_factory.py
• api/core/rag/datasource/vdb/vector_type.py
• api/fields/agent_fields.py
• api/models/account.py
• api/models/agent.py
• api/models/api_based_extension.py
• api/models/dataset.py
• api/models/model.py
• api/models/oauth.py
• api/models/provider.py
• api/models/source.py
• api/models/task.py
• api/models/tools.py
• api/models/trigger.py
• api/models/web.py
• api/models/workflow.py
• api/openapi/markdown/console-openapi.md
• api/pyproject.toml
• api/services/agent/composer_service.py
• api/services/agent/composer_validator.py
• api/services/agent/errors.py
• api/services/agent/observability_service.py
• api/services/agent/roster_service.py
• api/services/entities/agent_entities.py
• api/tests/unit_tests/configs/test_dify_config.py
• api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py
• api/tests/unit_tests/services/agent/test_agent_composer_entities.py
• api/tests/unit_tests/services/agent/test_agent_observability_service.py
• api/tests/unit_tests/services/agent/test_agent_services.py
• api/uv.lock
• cli/package.json
• dify-agent/pyproject.toml
• dify-agent/tests/local/test_packaging.py
• dify-agent/uv.lock
• docker/.env.example
• docker/docker-compose-template.yaml
• docker/docker-compose.middleware.yaml
• docker/docker-compose.yaml
• packages/contracts/generated/api/console/agent/orpc.gen.ts
• packages/contracts/generated/api/console/agent/types.gen.ts
• packages/contracts/generated/api/console/agent/zod.gen.ts
• packages/contracts/generated/api/console/apps/orpc.gen.ts
• packages/contracts/generated/api/console/apps/types.gen.ts
• packages/contracts/generated/api/console/apps/zod.gen.ts
• web/package.json

This page defines key terms, jargon, abbreviations, and domain concepts specific to the Dify codebase. Understanding these terms is crucial for new engineers to quickly grasp the system's architecture, data models, and operational workflows.

Core Concepts

Tenant

A "Tenant" represents a workspace or an organization within Dify. It acts as a logical isolation boundary for resources such as applications, datasets, and models. Each tenant has its own set of configurations, users, and data.

Code Pointers:

• Definition: Tenant class api/models/account.py32
• Tenant model in main models: _resolve_app_tenant_id function api/models/model.py73-77
• Multi-tenancy isolation in App model: tenant_id field api/models/model.py300-305

App

An "App" in Dify is a deployable application built using Dify's capabilities, such as a chatbot or a completion application. Apps are associated with a specific tenant and can have different execution modes (e.g., Chat, Completion, Workflow).

Code Pointers:

• Definition: App class api/models/model.py300
• App model configuration AppModelConfigDict TypedDict: api/models/model.py240-252
• App status enum: AppStatus api/models/model.py38

Dataset

A "Dataset" is a collection of documents or knowledge sources used for Retrieval-Augmented Generation (RAG). Datasets are tenant-specific and can be configured with various indexing techniques, retrieval models, and processing rules.

Code Pointers:

• Definition: Dataset class api/models/dataset.py165-211
• Dataset permissions: DatasetPermissionEnum api/models/dataset.py162-163
• Dataset Service logic: DatasetService class api/services/dataset_service.py1-50

Document

A "Document" is a single unit of content within a Dataset. It can be a text file, a web page, a Notion page, or other data sources. Documents undergo an indexing process to be made retrievable.

Code Pointers:

• Definition: Document class api/models/dataset.py240-280
• Indexing status enum: IndexingStatus api/models/enums.py56

Workflow

A "Workflow" in Dify represents a graph-based execution flow for AI applications. It consists of interconnected nodes, each performing a specific task (e.g., LLM call, tool execution, knowledge retrieval).

Code Pointers:

• Definition: Workflow class api/models/workflow.py176-210
• Workflow types (WORKFLOW, CHAT, RAG_PIPELINE): WorkflowType enum api/models/workflow.py115-123
• Workflow content structure: WorkflowContentDict TypedDict api/models/workflow.py99-105

RAG System Components

DatasetRetrieval

The DatasetRetrieval class orchestrates the retrieval process across one or more datasets, handling metadata filtering, reranking, and hit testing.

Code Pointers:

• Class definition: DatasetRetrieval class api/core/rag/retrieval/dataset_retrieval.py102
• knowledge_retrieval method: knowledge_retrieval method api/core/rag/retrieval/dataset_retrieval.py119-157

Diagram: Retrieval Logic Flow

Sources: api/core/rag/retrieval/dataset_retrieval.py119-157 api/core/workflow/nodes/knowledge_retrieval/knowledge_retrieval_node.py1-50 api/core/rag/datasource/vdb/vector_factory.py1-50

DocumentSegment

A DocumentSegment represents a chunk of a document after it has been split and processed. These segments are what get indexed and retrieved during RAG.

Code Pointers:

• Definition: DocumentSegment class api/models/dataset.py320
• Segment status enum: SegmentStatus api/models/enums.py56

KnowledgeFS

KnowledgeFS refers to the new frontend module (web/features/new-rag) that provides a unified interface for managing knowledge bases. It supports creating knowledge bases from various sources (empty, file upload, web, Notion, Google Drive, S3) and offers detailed document management, chunk viewing, and processing task tracking.

Code Pointers:

• Frontend module: web/features/new-rag web/app/components/base/icons/src/index.ts1-50 (indirectly, as a feature module)
• Source providers (Firecrawl, Notion, Google Drive, S3): ENABLE_WEBSITE_FIRECRAWL docker/.env.example158

Model and Provider Management

ModelManager

The ModelManager is the primary entry point for obtaining model instances and checking provider configurations.

Code Pointers:

• Class definition: ModelManager class api/core/model_manager.py28
• Usage in knowledge retrieval: ModelManager import api/core/rag/retrieval/dataset_retrieval.py28

ProviderManager

The ProviderManager handles the lifecycle and configuration of LLM providers. It assembles ProviderConfiguration objects which encapsulate all settings for a given provider.

Code Pointers:

• Class definition: LargeLanguageModel (base for providers) api/core/model_runtime/model_providers/base/large_language_model.py1-50
• Provider model: Provider class api/models/provider.py10

Diagram: Model Invocation Pipeline

Sources: api/core/model_manager.py28-30 api/core/rag/retrieval/dataset_retrieval.py102-118 api/models/model.py227-231

Tool and Plugin Ecosystem

ToolManager

The ToolManager is a central component for discovering and managing tools. It provides methods to retrieve different types of tool providers and their corresponding tool runtimes.

Code Pointers:

• Class definition: ToolManager class api/core/tools/tool_manager.py1-50
• Tool model: Tool class api/models/tools.py1-50

ToolProviderController

Dify manages tools through various controllers based on the provider type. These controllers abstract the specifics of each tool type.

Code Pointers:

• Tool provider controller logic: BuiltinToolManageService api/services/tools/builtin_tools_manage_service.py1-50
• Tool file signing: sign_tool_file function api/core/tools/signature.py22

Security and Access Control

TenantAccountRole

An enum defining the roles an account can have within a tenant. These roles dictate the permissions and access levels for users within a workspace.

Code Pointers:

• Enum definition: TenantAccountRole enum api/models/account.py12-18
• Usage in RBAC: account_role_required decorator api/controllers/console/wraps.py22-32

DatasetPermissionEnum

An enum defining the visibility and access permissions for a dataset. This controls who can view, edit, or use a dataset in applications.

Code Pointers:

• Enum definition: DatasetPermissionEnum api/models/dataset.py49

Infrastructure and Deployment

MODE Environment Variable

The MODE environment variable determines the entry point of the Dify API container. It can be set to api for the main web server, worker for Celery background tasks, beat for Celery scheduler, or job for one-off tasks.

Code Pointers:

• Worker configuration: x-shared-worker-config anchor docker/docker-compose.yaml74-79
• Beat configuration: x-shared-worker-beat-config anchor docker/docker-compose.yaml140-145
• Shared service config: x-shared-api-worker-config anchor docker/docker-compose-template.yaml2-8

Vector Database Abstraction

Dify supports over 23 vector databases through a plugin-like architecture, managed by the VectorFactory.

Code Pointers:

• Vector factory: VectorFactory class api/core/rag/datasource/vdb/vector_factory.py1-50
• Supported list in example: VECTOR_STORE environment variable api/.env.example207-208
• Workspace members for VDBs: [tool.uv.sources] section api/pyproject.toml65-94

Agent System

Agent

An "Agent" in Dify is an AI entity capable of reasoning, planning, and executing tasks using tools and knowledge.

Code Pointers:

• Agent configuration TypedDict: AgentToolConfig api/models/model.py142-147
• Agent mode config: AgentModeConfig api/models/model.py149-154
• Agent V2 toggle: NEXT_PUBLIC_ENABLE_AGENT_V2 environment variable docker/.env.example160

AgentSoulConfig

A Pydantic model representing the core configuration of an Agent's "soul," including its model, prompt, tools, knowledge, and memory settings. This configuration defines the agent's behavior and capabilities.

Code Pointers:

• Definition: AgentSoulConfig class api/services/entities/agent_entities.py100
• Example usage in tests: test_agent_soul_config_validation api/tests/unit_tests/services/agent/test_agent_services.py102-111
• Checking for model presence: AgentSoulConfig import api/services/agent/composer_validator.py1-50

AgentConfigSnapshot

A snapshot of an AgentSoulConfig at a specific point in time. This allows for versioning and reproducibility of agent configurations.

Code Pointers:

• Definition: AgentConfigSnapshot class api/models/agent.py100
• Used in AgentRosterService to retrieve published agent souls: get_published_agent_soul_config method api/services/agent/roster_service.py1-50

AgentConfigDraft

A draft version of an AgentSoulConfig that is actively being edited by a user. This allows for iterative development and testing before publishing.

Code Pointers:

• Definition: AgentConfigDraft class api/models/agent.py120
• Used by AgentComposerService for managing draft configurations: AgentComposerService class api/services/agent/composer_service.py1-50

AgentComposerService

A service responsible for managing the creation, editing, and validation of agent configurations, both for roster agents and workflow-embedded agents. It handles saving drafts, publishing, and managing different variants of agent configurations.

Code Pointers:

• Class definition: AgentComposerService class api/services/agent/composer_service.py1-50
• Loading workflow composer state: test_load_workflow_composer_state api/tests/unit_tests/services/agent/test_agent_services.py138-156

AgentRosterService

A service that manages the lifecycle of "roster" agents, which are standalone agents available for use across different applications and workflows. It handles CRUD operations, publishing, and versioning of these agents.

Code Pointers:

• Class definition: AgentRosterService class api/services/agent/roster_service.py1-50
• Retrieving published agent souls: test_get_published_agent_soul_config api/tests/unit_tests/services/agent/test_agent_services.py120-127

WorkflowAgentBinding

Represents the binding of an agent to a workflow node. This can be either a reference to a roster agent or an inline agent configuration specific to the workflow.

Code Pointers:

• Definition: WorkflowAgentBinding class api/models/agent.py160
• Binding types: WorkflowAgentBindingType enum api/models/agent.py150
• Used in AgentComposerService to load workflow agent configurations: AgentComposerService class api/services/agent/composer_service.py1-50

Diagram: Agent Configuration Flow

Sources: api/services/agent/composer_service.py1-50 api/services/agent/roster_service.py1-50 api/models/agent.py100-160 api/models/workflow.py176-210 api/models/model.py300

Dify Agent Runtime

A standalone FastAPI-based service built on the Agenton framework for executing Pydantic AI agents.

Code Pointers:

• Agent source dependency: dify-agent api/pyproject.toml63
• Agent lock version: dify-agent package dify-agent/uv.lock12-13

Go Agent Runtime (dify-agent-runtime)

A Go-based agent runtime that provides a secure and isolated environment for executing agent code. It features a shellctl HTTP server for managing shell jobs, tmux-backed shell job lifecycle, Landlock filesystem sandboxing, SQLite persistence for runner-exit, and a sanitize-pty PTY filter.

Code Pointers:

• dify-agent-runtime image: langgenius/dify-agent-runtime docker/docker-compose.middleware.yaml105 (This is an older reference, the current one is langgenius/dify-sandbox)
• Sandbox configuration: SANDBOX_API_KEY, SANDBOX_GIN_MODE, SANDBOX_WORKER_TIMEOUT docker/.env.example198-200
• Code execution endpoint: CODE_EXECUTION_ENDPOINT api/configs/feature/__init__.py109-111

Deployments

Deployments Feature

The "Deployments" feature (web/features/deployments) in the frontend manages the lifecycle of application releases. This includes creating new releases, maintaining version history, importing/exporting workflow DSL, and managing deployments across different environments (production, staging, development). It also handles access channels (webapp, CLI) and environment-specific permission policies.

Code Pointers:

• Frontend module: web/features/deployments (implied by feature name)
• Jotai-Tanstack-Query state layer: jotai-tanstack-query dependency web/package.json102
• API contracts: packages/contracts/generated/api/console/apps/orpc.gen.ts packages/contracts/generated/api/console/apps/orpc.gen.ts1-50
• API contracts (types): packages/contracts/generated/api/console/apps/types.gen.ts packages/contracts/generated/api/console/apps/types.gen.ts1-50
• API contracts (Zod schemas): packages/contracts/generated/api/console/apps/zod.gen.ts packages/contracts/generated/api/console/apps/zod.gen.ts1-50

Frontend Concepts

jotai-tanstack-query

A state management layer used in the Dify web frontend. It combines Jotai for atomic state management with TanStack Query for data fetching.

Code Pointers:

• jotai-tanstack-query dependency: web/package.json102
• TanStack Query core: @tanstack/query-core dependency web/package.json68

dify-ui

A shared component library used across the Dify web frontend.

Code Pointers:

• @langgenius/dify-ui dependency: web/package.json159

Sources: api/models/model.py1-248 api/models/workflow.py1-210 api/models/account.py1-100 api/core/rag/retrieval/dataset_retrieval.py102-157 docker/docker-compose.yaml1-206 api/pyproject.toml1-100 api/.env.example1-211 web/package.json1-200 api/models/dataset.py1-320 api/services/entities/agent_entities.py100 api/tests/unit_tests/services/agent/test_agent_services.py102-156 api/services/agent/composer_validator.py1-50 api/models/agent.py100-160 api/services/agent/roster_service.py1-50 api/services/agent/composer_service.py1-50 dify-agent/uv.lock12-13 docker/docker-compose.middleware.yaml105 api/configs/feature/__init__.py109-111 packages/contracts/generated/api/console/apps/orpc.gen.ts1-50 packages/contracts/generated/api/console/apps/types.gen.ts1-50 packages/contracts/generated/api/console/apps/zod.gen.ts1-50