Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
"""Shell-backed config pulls with instructions derived from current Config.
Only pull results and successful initialization persist. The manifest and CLI
help are rendered from current configuration and the installed CLI reference.
"""
from __future__ import annotations
import json
import shlex
from dataclasses import dataclass
from typing import override
from pydantic_ai import RunContext
from pydantic_ai.capabilities import AbstractCapability, CapabilityOrdering
from pydantic_ai.capabilities.abstract import WrapRunHandler
from pydantic_ai.run import AgentRunResult
from dify_agent.runtime.context import Deps
from dify_agent.layers._agent_cli_help import render_agent_stub_cli_help
from dify_agent.layers._agent_file_cli_help import AGENT_FILE_UPLOAD_REPLY_HINT as _AGENT_FILE_UPLOAD_REPLY_HINT
from dify_agent.layers.config.configs import (
DifyConfigLayerConfig,
DifyConfigRuntimeState,
)
from dify_agent.layers.shell.layer import Capability as ShellCapability, ShellSession
_CONFIG_CONTEXT_HEADING = "Current Agent config manifest for this run:"
_CONFIG_CONTEXT_COMMAND = "dify-agent config manifest"
_CONFIG_CLI_USAGE_PROMPT = """`dify-agent` is an installed CLI tool in the shell environment. Use it directly in shell_run scripts.
The command outputs below are generated from the `dify-agent` CLI available in this run. Use them as the source of truth
for command names, arguments, and options.
Config persistence rules:
- Local shell edits to config files, skills, env, notes, or the prompt are not saved by themselves.
- To persist an Agent config change, run the matching `dify-agent config ...` mutation command.
- Mutation commands are available only when the manifest shows `config_version.kind` as `build_draft` and
`config_version.writable` as true.
- `config prompt pull` reads the raw system prompt, including unexpanded mention markers. Edit the local file and
run `config prompt push` to persist it. Only subsequent run requests built from that draft use the saved prompt;
already-built run requests keep their prompt."""
_CONFIG_CLI_HELP_COMMANDS: dict[str, tuple[str, ...]] = {
"dify-agent config --help": ("config",),
"dify-agent config manifest --help": ("config", "manifest"),
"dify-agent config skills pull --help": ("config", "skills", "pull"),
"dify-agent config files pull --help": ("config", "files", "pull"),
"dify-agent config note pull --help": ("config", "note", "pull"),
"dify-agent config prompt pull --help": ("config", "prompt", "pull"),
}
_CONFIG_CLI_MUTATION_HELP_COMMANDS: dict[str, tuple[str, ...]] = {
"dify-agent config note push --help": ("config", "note", "push"),
"dify-agent config prompt push --help": ("config", "prompt", "push"),
"dify-agent config env push --help": ("config", "env", "push"),
"dify-agent config files push --help": ("config", "files", "push"),
"dify-agent config files delete --help": ("config", "files", "delete"),
"dify-agent config skills push --help": ("config", "skills", "push"),
"dify-agent config skills delete --help": ("config", "skills", "delete"),
}
_AGENT_FILE_CLI_HELP_COMMANDS: dict[str, tuple[str, ...]] = {
"dify-agent file upload --help": ("file", "upload"),
"dify-agent file public-url --help": ("file", "public-url"),
"dify-agent file download --help": ("file", "download"),
}
_CONFIG_CONTEXT_EXCLUDE = {"mentioned_skill_names": True, "mentioned_file_names": True, "shell": True}
class DifyConfigLayerError(RuntimeError):
"""Raised when one eager-pull config operation fails."""
class Config(DifyConfigLayerConfig):
pass
class State(DifyConfigRuntimeState):
initialized: bool = False
class Capability(AbstractCapability[Deps]):
"""First-run eager pulls with explicit JSON writeback and native ordering."""
def __init__(self, name: str):
self.id = name
self.name = name
@override
def get_ordering(self) -> CapabilityOrdering:
return CapabilityOrdering(wrapped_by=[ShellCapability], requires=[ShellCapability])
@override
def get_instructions(self):
return self._instructions
def _instructions(self, ctx: RunContext[Deps]) -> str:
context = self._context(ctx.deps)
return f"{context.build_prompt_context()}\n\n{context.build_suffix_prompt()}"
def _context(self, deps: Deps) -> _ConfigContext:
config = Config.model_validate(deps.layers[self.name]["config"])
return _ConfigContext(
config, State.model_validate(deps.layers[self.name]["state"]), deps.resources.shells[config.shell]
)
@override
async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:
context = self._context(ctx.deps)
try:
if not context.runtime_state.initialized:
await context._pull_mentioned_targets()
context.runtime_state.initialized = True
finally:
ctx.deps.layers[self.name]["state"] = context.runtime_state.model_dump(mode="json")
return await handler()
@dataclass
class _ConfigContext:
"""Short-lived validated data for prompt rendering or an eager-pull operation."""
config: Config
runtime_state: State
shell: ShellSession
def build_prompt_context(self) -> str:
sections: list[str] = []
loaded_skill_sections = []
for name in self.config.mentioned_skill_names:
output = self.runtime_state.pulled_skill_outputs.get(name)
if output is None:
continue
command = f"dify-agent config skills pull {shlex.quote(name)}"
loaded_skill_sections.append(
f"Name: {name}\nPull command output for this run:\n{_format_command_output(command, output)}"
)
if loaded_skill_sections:
sections.append("Loaded mentioned skills:\n\n" + "\n\n".join(loaded_skill_sections))
mentioned_file_sections = []
for name in self.config.mentioned_file_names:
output = self.runtime_state.pulled_file_outputs.get(name)
if output is None:
continue
command = f"dify-agent config files pull {shlex.quote(name)}"
mentioned_file_sections.append(
f"Name: {name}\nPull command output for this run:\n{_format_command_output(command, output)}"
)
if mentioned_file_sections:
sections.append("Mentioned files pulled locally:\n\n" + "\n\n".join(mentioned_file_sections))
return "\n\n".join(section for section in sections if section)
def build_suffix_prompt(self) -> str:
sections = [
f"{_CONFIG_CONTEXT_HEADING}\n"
f"{_format_command_output(_CONFIG_CONTEXT_COMMAND, self._format_config_context_json())}"
]
usage_lines = [_CONFIG_CLI_USAGE_PROMPT, self._format_config_cli_help(), self._format_agent_file_cli_help()]
sections.append("\n".join(usage_lines))
return "\n\n".join(section for section in sections if section)
@property
def _config_writable(self) -> bool:
return self.config.config_version is not None and self.config.config_version.writable
def _format_config_cli_help(self) -> str:
commands = dict(_CONFIG_CLI_HELP_COMMANDS)
if self._config_writable:
commands.update(_CONFIG_CLI_MUTATION_HELP_COMMANDS)
command_sections = [
_format_command_output(command, render_agent_stub_cli_help(args)) for command, args in commands.items()
]
return "Agent config CLI reference for installed `dify-agent`:\n" + "\n\n".join(command_sections)
def _format_agent_file_cli_help(self) -> str:
command_sections = [
_format_command_output(command, render_agent_stub_cli_help(args))
for command, args in _AGENT_FILE_CLI_HELP_COMMANDS.items()
]
return (
"Agent file CLI reference for installed `dify-agent`:\n"
+ "\n\n".join(command_sections)
+ f"\n\n{_AGENT_FILE_UPLOAD_REPLY_HINT}"
)
def _format_config_context_json(self) -> str:
return self.config.model_dump_json(exclude=_CONFIG_CONTEXT_EXCLUDE, exclude_none=True)
async def _pull_mentioned_targets(self) -> None:
self.runtime_state.pulled_skill_outputs = {}
self.runtime_state.pulled_file_outputs = {}
if not self.config.mentioned_skill_names and not self.config.mentioned_file_names:
return
if names := self.config.mentioned_skill_names:
output = await self._run_mentioned_pull(
script=self._build_shell_skill_pull_script(names),
target_kind="skill",
)
self.runtime_state.pulled_skill_outputs = _parse_skill_pull_outputs(output, names)
if names := self.config.mentioned_file_names:
output = await self._run_mentioned_pull(
script=self._build_shell_file_pull_script(names),
target_kind="file",
)
self.runtime_state.pulled_file_outputs = _parse_file_pull_outputs(output, names)
async def _run_mentioned_pull(self, *, script: str, target_kind: str) -> str:
result = await self.shell.run_remote_script(
script,
inject_agent_stub_env=True,
)
if result.exit_code != 0:
raise DifyConfigLayerError(
f"config mentioned {target_kind} pull failed in shell: "
f"{result.status} exit_code={result.exit_code}\n{result.output}"
)
if not result.output_complete:
reason = result.incomplete_reason or "unknown"
raise DifyConfigLayerError(
f"config mentioned {target_kind} pull output was incomplete before the payload finished: {reason}"
)
output = result.output.strip()
if not output:
raise DifyConfigLayerError(f"missing pull output for mentioned config {target_kind}s")
return output
def _build_shell_skill_pull_script(self, names: list[str]) -> str:
targets = " ".join(shlex.quote(name) for name in names)
return f"set -eu\ndify-agent config skills pull --json {targets}"
def _build_shell_file_pull_script(self, names: list[str]) -> str:
targets = " ".join(shlex.quote(name) for name in names)
return f"set -eu\ndify-agent config files pull --json {targets}"
def _parse_skill_pull_outputs(output: str, expected_names: list[str]) -> dict[str, str]:
items = _parse_pull_items(output, target_kind="skill")
parsed: dict[str, str] = {}
for name in expected_names:
item = items.get(name)
if item is None:
raise DifyConfigLayerError(f"missing pull output for mentioned config skill {name}")
directory_path = item.get("directory_path")
skill_md = item.get("skill_md")
if not isinstance(directory_path, str) or not directory_path:
raise DifyConfigLayerError(f"invalid directory path in pull output for mentioned config skill {name}")
if not isinstance(skill_md, str):
raise DifyConfigLayerError(f"invalid skill content in pull output for mentioned config skill {name}")
parsed[name] = f"{directory_path}\n{skill_md}".strip()
return parsed
def _parse_file_pull_outputs(output: str, expected_names: list[str]) -> dict[str, str]:
items = _parse_pull_items(output, target_kind="file")
parsed: dict[str, str] = {}
for name in expected_names:
item = items.get(name)
if item is None:
raise DifyConfigLayerError(f"missing pull output for mentioned config file {name}")
path = item.get("path")
if not isinstance(path, str) or not path:
raise DifyConfigLayerError(f"invalid path in pull output for mentioned config file {name}")
parsed[name] = path
return parsed
def _parse_pull_items(output: str, *, target_kind: str) -> dict[str, dict[str, object]]:
try:
payload: object = json.loads(output)
except json.JSONDecodeError as exc:
raise DifyConfigLayerError(f"invalid JSON pull output for mentioned config {target_kind}s") from exc
if not isinstance(payload, dict):
raise DifyConfigLayerError(f"invalid pull output for mentioned config {target_kind}s")
raw_items = payload.get("items")
if not isinstance(raw_items, list):
raise DifyConfigLayerError(f"missing items in pull output for mentioned config {target_kind}s")
items: dict[str, dict[str, object]] = {}
for raw_item in raw_items:
if not isinstance(raw_item, dict):
raise DifyConfigLayerError(f"invalid item in pull output for mentioned config {target_kind}s")
item = {str(key): value for key, value in raw_item.items()}
name = item.get("name")
if not isinstance(name, str) or not name:
raise DifyConfigLayerError(f"missing item name in pull output for mentioned config {target_kind}s")
items[name] = item
return items
def _format_command_output(command: str, output: str) -> str:
return f"Command:\n$ {command}\nOutput:\n{output}"
__all__ = ["Config", "State", "Capability", "DifyConfigLayerError"]