Agent V2 Variable System#

Agent V2 uses a dual-variable architecture that separates operator-side environment configuration (env) from end-user-facing input variables (app_variables). Both live inside the top-level AgentSoulConfig JSON snapshot.

Dual-Variable Architecture#

env — Operator Environment Configuration#

AgentSoulEnvConfig holds two lists:

AgentEnvVariableConfig carries name, key, env_name, variable, type, value, default, and required. The various name/key aliases exist for backward compatibility.

AgentSecretRefConfig adds id, ref, credential_id, provider_credential_id, and provider to support backend-managed credential lookups. Secret values are never stored in the config snapshot; a reference ID is stored instead, and the actual value is resolved at runtime.

CLI tools can also carry their own scoped environment via AgentCliToolEnvConfig, which wraps the same variables / secret_refs lists per tool.

app_variables — User Input Variables#

AppVariableConfig defines typed, user-facing input slots presented to the end-user at chat time:

name: str # displayed label and variable reference key
type: str # textInput, paragraph, select, number, json, etc.
required: bool
default: Any

These become the user_input_form rendered before a conversation starts 1 and are mapped to InputForm objects for the preview UI via getAgentSoulInputsForm.

Frontend Store & Conversion#

The frontend models both variable types as a unified EnvVariable record:

type EnvScope = 'secret' | 'plain'
type EnvVariable = { id: string; key: string; value: string; scope: EnvScope; masked?: boolean }

Jotai atoms in store-modules/env.ts expose agentComposerEnvVariablesAtom plus individual setter atoms (setEnvVariableKeyAtom, setEnvVariableScopeAtom, setEnvVariableValueAtom, addEnvVariableAtom, importEnvVariablesAtom, removeEnvVariableAtom).

The bidirectional conversion between the backend schema and this flat array lives in conversions.ts:

• Backend → Frontend: toEnvVariableFormState() maps env.variables → scope: 'plain' and env.secret_refs → scope: 'secret', masked: true 2.
• Frontend → Backend: toEnvConfig() splits the array back on scope to repopulate variables and secret_refs 3.

Environment Variables Editor UI#

The AgentEnvEditor component renders a table-style editor in the Advanced Settings panel of the agent configure view. Key behaviors:

• Column layout: KEY | VALUE | DELETE
• Plain text only: Environment variables are stored and displayed as plain text. The scope selection (plain/secret) and secret masking features are behind a disabled feature flag (ENABLE_AGENT_SECRET_ENV_VARIABLES = false) and are not visible in the UI.
• .env file import: A hidden <input type="file"> triggers parseEnvImport(), which parses standard dotenv syntax (quoted values, export prefixes, inline # comments, escape sequences). Invalid lines are counted and toasted as an error; valid entries are appended with scope: 'plain' by default 7.
• Key validation: Spaces are auto-replaced with underscores; keys must pass the checkKeys() validator 8.

Runtime Flow: env → Shell Layer#

At run time, AgentSoulConfig.env is converted to DifyShellLayerConfig and sent to the dify-agent backend:

• Plain variables and inline secrets → DifyShellEnvVarConfig (name + value, ephemeral, not persisted to workspace) 9
• Backend-managed secret refs (no inline value) → DifyShellSecretRefConfig (name + ref ID; actual value resolved by the backend) 10

The split prevents secret values from travelling as plaintext in run requests. CLI tool-scoped env and secret_refs undergo the same transformation independently 11.

Comparison: Legacy ConfigVar vs. Agent V2 Variables#

The legacy ConfigVar component is still used by non-V2 chat and completion app configuration (see config/index.tsx). Agent V2 agents do not use it.

Key Source Files#