Skip to content

armgit / dify

Public Imported from GitHub
0

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.

refactor(agent): replace Agenton with native Pydantic AI modules (#43833)

盐粒 Yanlicc14bb83e0f5
diff --git a/api/clients/agent_backend/__init__.py b/api/clients/agent_backend/__init__.py
index dbdc93cfbad..f4936663b9b 100644
--- a/api/clients/agent_backend/__init__.py
+++ b/api/clients/agent_backend/__init__.py
@@ -17,7 +17,6 @@ from clients.agent_backend.errors import (
)
from clients.agent_backend.event_adapter import (
AgentBackendAgentMessageDeltaInternalEvent,
- AgentBackendDeferredToolCallInternalEvent,
AgentBackendInternalEvent,
AgentBackendInternalEventType,
AgentBackendRunCancelledInternalEvent,
@@ -57,7 +56,6 @@ __all__ = [
"WORKFLOW_USER_PROMPT_LAYER_ID",
"AgentBackendAgentAppRunInput",
"AgentBackendAgentMessageDeltaInternalEvent",
- "AgentBackendDeferredToolCallInternalEvent",
"AgentBackendError",
"AgentBackendHTTPError",
"AgentBackendInternalEvent",
diff --git a/api/clients/agent_backend/event_adapter.py b/api/clients/agent_backend/event_adapter.py
index a8850ada4ec..b692ba437df 100644
--- a/api/clients/agent_backend/event_adapter.py
+++ b/api/clients/agent_backend/event_adapter.py
@@ -2,9 +2,7 @@
The adapter does not define a new cross-service event contract. It consumes
``dify_agent.protocol.RunEvent`` and produces small API-internal models that the
-workflow Agent Node maps to Graphon/AppQueue events. Deferred external tool calls
-remain Dify Agent ``run_succeeded`` payloads on the wire; API code turns them
-into an internal event so workflow pause/session handling stays local to API.
+workflow Agent Node maps to Graphon/AppQueue events.
Agent-message deltas are exposed as annotations on ``PydanticAIStreamRunEvent``
so API code does not have to parse Pydantic AI stream-event internals to
preserve streaming. The terminal answer remains the ``run_succeeded`` output.
@@ -15,9 +13,7 @@ from __future__ import annotations
from enum import StrEnum
from typing import Annotated, Literal, cast
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.protocol import (
- DeferredToolCallPayload,
PydanticAIStreamRunEvent,
RunCancelledEvent,
RunEvent,
@@ -26,6 +22,7 @@ from dify_agent.protocol import (
RunStartedEvent,
RunSucceededEvent,
)
+from dify_agent.protocol.snapshot import SessionSnapshot
from pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter
_EVENT_DATA_ADAPTER = TypeAdapter(object)
@@ -37,7 +34,6 @@ class AgentBackendInternalEventType(StrEnum):
RUN_STARTED = "run_started"
STREAM_EVENT = "stream_event"
AGENT_MESSAGE_DELTA = "agent_message_delta"
- DEFERRED_TOOL_CALL = "deferred_tool_call"
RUN_SUCCEEDED = "run_succeeded"
RUN_FAILED = "run_failed"
RUN_CANCELLED = "run_cancelled"
@@ -78,17 +74,7 @@ class AgentBackendRunSucceededInternalEvent(AgentBackendInternalEventBase):
type: Literal[AgentBackendInternalEventType.RUN_SUCCEEDED] = AgentBackendInternalEventType.RUN_SUCCEEDED
output: JsonValue
- session_snapshot: CompositorSessionSnapshot
- usage: dict[str, JsonValue] | None = None
-
-
-class AgentBackendDeferredToolCallInternalEvent(AgentBackendInternalEventBase):
- """API-internal representation of a Dify Agent deferred external tool call."""
-
- type: Literal[AgentBackendInternalEventType.DEFERRED_TOOL_CALL] = AgentBackendInternalEventType.DEFERRED_TOOL_CALL
- deferred_tool_call: DeferredToolCallPayload
- message: str | None = None
- session_snapshot: CompositorSessionSnapshot
+ session_snapshot: SessionSnapshot
usage: dict[str, JsonValue] | None = None
@@ -99,7 +85,7 @@ class AgentBackendRunFailedInternalEvent(AgentBackendInternalEventBase):
error: str
error_type: RunFailureType | None = None
reason: str | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
+ session_snapshot: SessionSnapshot | None = None
usage: dict[str, JsonValue] | None = None
@@ -109,7 +95,7 @@ class AgentBackendRunCancelledInternalEvent(AgentBackendInternalEventBase):
type: Literal[AgentBackendInternalEventType.RUN_CANCELLED] = AgentBackendInternalEventType.RUN_CANCELLED
reason: str | None = None
message: str | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
+ session_snapshot: SessionSnapshot | None = None
usage: dict[str, JsonValue] | None = None
@@ -117,7 +103,6 @@ type AgentBackendInternalEvent = Annotated[
AgentBackendRunStartedInternalEvent
| AgentBackendStreamInternalEvent
| AgentBackendAgentMessageDeltaInternalEvent
- | AgentBackendDeferredToolCallInternalEvent
| AgentBackendRunSucceededInternalEvent
| AgentBackendRunFailedInternalEvent
| AgentBackendRunCancelledInternalEvent,
@@ -158,19 +143,6 @@ class AgentBackendRunEventAdapter:
)
]
case RunSucceededEvent():
- if "deferred_tool_call" in event.data.model_fields_set:
- if event.data.deferred_tool_call is None:
- raise TypeError("run_succeeded deferred_tool_call branch is missing payload")
- return [
- AgentBackendDeferredToolCallInternalEvent(
- run_id=event.run_id,
- source_event_id=event.id,
- deferred_tool_call=event.data.deferred_tool_call,
- message=_deferred_tool_call_message(event.data.deferred_tool_call),
- session_snapshot=event.data.session_snapshot,
- usage=_agent_run_usage(event.data.usage),
- )
- ]
return [
AgentBackendRunSucceededInternalEvent(
run_id=event.run_id,
@@ -206,21 +178,6 @@ class AgentBackendRunEventAdapter:
raise TypeError(f"unsupported agent backend run event: {type(event).__name__}")
-def _deferred_tool_call_message(payload: DeferredToolCallPayload) -> str:
- """Return a concise workflow pause message from deferred-tool arguments."""
- args = payload.args
- if isinstance(args, dict):
- question = args.get("question")
- if isinstance(question, str) and question.strip():
- return question
-
- title = args.get("title")
- if isinstance(title, str) and title.strip():
- return title
-
- return f"Agent backend requested external input via deferred tool '{payload.tool_name}'."
-
-
def _agent_run_usage(usage: object | None) -> dict[str, JsonValue] | None:
"""Return JSON-safe usage metadata from optional Agent backend usage."""
if usage is None:
diff --git a/api/clients/agent_backend/fake_client.py b/api/clients/agent_backend/fake_client.py
index c016f2ce6bf..1fe7b3660c9 100644
--- a/api/clients/agent_backend/fake_client.py
+++ b/api/clients/agent_backend/fake_client.py
@@ -11,13 +11,11 @@ from collections.abc import Callable, Iterator
from datetime import UTC, datetime
from enum import StrEnum
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.protocol import (
CancelRunRequest,
CancelRunResponse,
CreateRunRequest,
CreateRunResponse,
- DeferredToolCallPayload,
RunCancelledEvent,
RunCancelledEventData,
RunEvent,
@@ -28,6 +26,7 @@ from dify_agent.protocol import (
RunSucceededEvent,
RunSucceededEventData,
)
+from dify_agent.protocol.snapshot import SessionSnapshot
_FIXED_TIME = datetime(2026, 1, 1, tzinfo=UTC)
@@ -41,7 +40,6 @@ class FakeAgentBackendScenario(StrEnum):
SUCCESS = "success"
FAILED = "failed"
- PAUSED = "paused"
class FakeAgentBackendRunClient:
@@ -89,7 +87,7 @@ class FakeAgentBackendRunClient:
data=RunCancelledEventData(
reason=request.reason,
message=request.message,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(),
),
)
@@ -127,13 +125,6 @@ class FakeAgentBackendRunClient:
updated_at=_FIXED_TIME,
error="fake failure",
)
- case FakeAgentBackendScenario.PAUSED:
- return RunStatusResponse(
- run_id=run_id,
- status="succeeded",
- created_at=_FIXED_TIME,
- updated_at=_FIXED_TIME,
- )
def _events(self, run_id: str) -> tuple[RunEvent, ...]:
match self.scenario:
@@ -146,7 +137,7 @@ class FakeAgentBackendRunClient:
created_at=_FIXED_TIME,
data=RunSucceededEventData(
output={"text": "hello agent"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(),
),
),
)
@@ -160,25 +151,7 @@ class FakeAgentBackendRunClient:
data=RunFailedEventData(
error="fake failure",
reason="unit_test",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
- ),
- ),
- )
- case FakeAgentBackendScenario.PAUSED:
- return (
- RunStartedEvent(id="1-0", run_id=run_id, created_at=_FIXED_TIME),
- RunSucceededEvent(
- id="2-0",
- run_id=run_id,
- created_at=_FIXED_TIME,
- data=RunSucceededEventData(
- deferred_tool_call=DeferredToolCallPayload(
- tool_call_id="fake-ask-human-1",
- tool_name="ask_human",
- args={"question": "Agent requested human input."},
- metadata={"layer_type": "dify.ask_human", "schema_version": 1},
- ),
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(),
),
),
)
diff --git a/api/clients/agent_backend/request_builder.py b/api/clients/agent_backend/request_builder.py
index d7a3b8ddc38..47b007cd99c 100644
--- a/api/clients/agent_backend/request_builder.py
+++ b/api/clients/agent_backend/request_builder.py
@@ -3,10 +3,9 @@
This module is intentionally an adapter, not a wire DTO package. The emitted
object is always ``dify_agent.protocol.CreateRunRequest`` so the Agent backend
protocol has a single owner. API-only context such as Agent Soul vs workflow job
-prompt is preserved in layer names and metadata until the dedicated product
-schemas land in later phases. Dify-owned execution identifiers are emitted as an
-explicit ``dify.execution_context`` layer so the run request stays fully
-composition-driven.
+prompt is preserved in registered module names. Execution identifiers live in
+execution_context Config; model, tool and resource references are explicit Config
+fields. The wire request contains current Config and optional state-only snapshot.
"""
from __future__ import annotations
@@ -15,29 +14,21 @@ import re
from collections.abc import Mapping
from typing import ClassVar, Literal
-from agenton.compositor import CompositorSessionSnapshot
-from agenton.layers import ExitIntent
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
-from dify_agent.layers.config import DIFY_CONFIG_LAYER_TYPE_ID, DifyConfigLayerConfig
-from dify_agent.layers.dify_core_tools import DIFY_CORE_TOOLS_LAYER_TYPE_ID, DifyCoreToolsLayerConfig
+from dify_agent.layers.config import DifyConfigLayerConfig
+from dify_agent.layers.dify_core_tools import DifyCoreToolsLayerConfig
from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
DifyPluginLLMLayerConfig,
DifyPluginToolsLayerConfig,
)
from dify_agent.layers.execution_context import (
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
DifyExecutionContextLayerConfig,
)
-from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
+from dify_agent.layers.knowledge import DifyKnowledgeBaseLayerConfig
+from dify_agent.layers.output import DifyOutputLayerConfig
+from dify_agent.layers.prompt import Config as PromptConfig
+from dify_agent.layers.runtime import DifyRuntimeLayerConfig
+from dify_agent.layers.shell import DifyShellLayerConfig
from dify_agent.layers.user_prompt import (
- DIFY_USER_PROMPT_LAYER_TYPE_ID,
DifyUserPromptFileConfig,
DifyUserPromptLayerConfig,
)
@@ -46,11 +37,10 @@ from dify_agent.protocol import (
DIFY_AGENT_MODEL_LAYER_ID,
DIFY_AGENT_OUTPUT_LAYER_ID,
CreateRunRequest,
- DeferredToolResultsPayload,
- LayerExitSignals,
RunComposition,
RunLayerSpec,
)
+from dify_agent.protocol.snapshot import SessionSnapshot
from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
AGENT_SOUL_PROMPT_LAYER_ID = "agent_soul_prompt"
@@ -63,22 +53,10 @@ DIFY_CONFIG_LAYER_ID = "config"
DIFY_PLUGIN_TOOLS_LAYER_ID = "tools"
DIFY_CORE_TOOLS_LAYER_ID = "core_tools"
DIFY_KNOWLEDGE_BASE_LAYER_ID = "knowledge"
-DIFY_ASK_HUMAN_LAYER_ID = "ask_human"
DIFY_SHELL_LAYER_ID = "shell"
type AgentConfigVersionKind = Literal["snapshot", "draft", "build_draft"]
-def _shell_layer_deps() -> dict[str, str]:
- return {
- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,
- "runtime": DIFY_RUNTIME_LAYER_ID,
- }
-
-
-def _config_layer_deps() -> dict[str, str]:
- return {"shell": DIFY_SHELL_LAYER_ID}
-
-
def _markdown_backtick_fence(text: str) -> str:
"""Choose a fence that will not terminate inside the prompt body."""
longest_backtick_run = max((len(match.group(0)) for match in re.finditer(r"`+", text)), default=0)
@@ -213,18 +191,9 @@ class AgentBackendWorkflowNodeRunInput(BaseModel):
core_tools: DifyCoreToolsLayerConfig | None = None
knowledge: DifyKnowledgeBaseLayerConfig | None = None
config_layer_config: DifyConfigLayerConfig | None = None
- # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
- # the Agent Soul configures human involvement; a deferred call ends the run and
- # the workflow pauses via the existing HITL form mechanism (ENG-635).
- ask_human_config: DifyAskHumanLayerConfig | None = None
- # Inject the sandboxed shell graph. Requires a deployment-selected runtime
- # backend plus the product-resolved persistent Binding.
include_shell: bool = False
shell_config: DifyShellLayerConfig | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
- # Human tool results fed back into a continuation run after a HITL submission
- # (ENG-638). Keyed by the original deferred tool_call_id.
- deferred_tool_results: DeferredToolResultsPayload | None = None
+ session_snapshot: SessionSnapshot | None = None
include_history: bool = True
metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -260,17 +229,9 @@ class AgentBackendAgentAppRunInput(BaseModel):
core_tools: DifyCoreToolsLayerConfig | None = None
knowledge: DifyKnowledgeBaseLayerConfig | None = None
config_layer_config: DifyConfigLayerConfig | None = None
- # Human-in-the-loop ask_human deferred tool (dify.ask_human). Present only when
- # the Agent Soul configures human involvement (ENG-635).
- ask_human_config: DifyAskHumanLayerConfig | None = None
- # Inject the sandboxed shell graph. Requires a deployment-selected runtime
- # backend plus the product-resolved persistent Binding.
include_shell: bool = False
shell_config: DifyShellLayerConfig | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
- # Human tool results fed back into a continuation run after a HITL submission
- # (ENG-638). Keyed by the original deferred tool_call_id.
- deferred_tool_results: DeferredToolResultsPayload | None = None
+ session_snapshot: SessionSnapshot | None = None
include_history: bool = True
metadata: dict[str, JsonValue] = Field(default_factory=dict)
@@ -293,7 +254,7 @@ class AgentBackendRunRequestBuilder:
Layer graph: optional Agent Soul system prompt → user prompt →
execution context → optional shell / config / history
(multi-turn) → LLM → optional plugin-direct tools / core-routed tools /
- knowledge search / ask_human / structured output. Mirrors the
+ knowledge search / structured output. Mirrors the
workflow-node layer ordering minus the workflow-job / previous-node
prompt.
"""
@@ -306,9 +267,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=AGENT_SOUL_PROMPT_LAYER_ID,
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "agent_soul"},
- config=PromptLayerConfig(prefix=agent_soul_prompt),
+ config=(PromptConfig(prefix=agent_soul_prompt)).model_dump(mode="json"),
)
)
@@ -316,15 +275,13 @@ class AgentBackendRunRequestBuilder:
[
RunLayerSpec(
name=AGENT_APP_USER_PROMPT_LAYER_ID,
- type=DIFY_USER_PROMPT_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "agent_app_user_prompt"},
- config=DifyUserPromptLayerConfig(text=run_input.user_prompt, files=run_input.user_files),
+ config=(
+ DifyUserPromptLayerConfig(text=run_input.user_prompt, files=run_input.user_files)
+ ).model_dump(mode="json"),
),
RunLayerSpec(
name=DIFY_EXECUTION_CONTEXT_LAYER_ID,
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=run_input.execution_context,
+ config=(run_input.execution_context).model_dump(mode="json"),
),
]
)
@@ -334,9 +291,9 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_RUNTIME_LAYER_ID,
- type=DIFY_RUNTIME_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),
+ config=(DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref)).model_dump(
+ mode="json"
+ ),
)
)
# Sandboxed bash workspace (dify.shell). It enters before config so
@@ -344,10 +301,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_SHELL_LAYER_ID,
- type=DIFY_SHELL_LAYER_TYPE_ID,
- deps=_shell_layer_deps(),
- metadata=run_input.metadata,
- config=run_input.shell_config or DifyShellLayerConfig(),
+ config=(run_input.shell_config or DifyShellLayerConfig()).model_dump(mode="json"),
)
)
@@ -355,10 +309,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_CONFIG_LAYER_ID,
- type=DIFY_CONFIG_LAYER_TYPE_ID,
- deps=_config_layer_deps(),
- metadata=run_input.metadata,
- config=run_input.config_layer_config,
+ config=(run_input.config_layer_config).model_dump(mode="json"),
)
)
@@ -366,38 +317,31 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_AGENT_HISTORY_LAYER_ID,
- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "agent_session_history"},
)
)
layers.append(
RunLayerSpec(
name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
- metadata=run_input.metadata,
- config=DifyPluginLLMLayerConfig(
- plugin_id=run_input.model.plugin_id,
- model_provider=run_input.model.model_provider,
- model=run_input.model.model,
- model_settings=_agent_model_settings(run_input.model.model_settings),
- context_window_tokens=run_input.model.context_window_tokens,
- ),
+ config=(
+ DifyPluginLLMLayerConfig(
+ plugin_id=run_input.model.plugin_id,
+ model_provider=run_input.model.model_provider,
+ model=run_input.model.model,
+ model_settings=_agent_model_settings(run_input.model.model_settings),
+ context_window_tokens=run_input.model.context_window_tokens,
+ )
+ ).model_dump(mode="json"),
)
)
if run_input.tools is not None and run_input.tools.tools:
- plugin_tool_deps = {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
- if include_shell:
- plugin_tool_deps["shell"] = DIFY_SHELL_LAYER_ID
layers.append(
RunLayerSpec(
name=DIFY_PLUGIN_TOOLS_LAYER_ID,
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps=plugin_tool_deps,
- metadata=run_input.metadata,
- config=run_input.tools,
+ config=(
+ run_input.tools.model_copy(update={"shell": DIFY_SHELL_LAYER_ID if include_shell else None})
+ ).model_dump(mode="json"),
)
)
@@ -405,10 +349,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_CORE_TOOLS_LAYER_ID,
- type=DIFY_CORE_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
- metadata=run_input.metadata,
- config=run_input.core_tools,
+ config=(run_input.core_tools).model_dump(mode="json"),
)
)
@@ -416,23 +357,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_KNOWLEDGE_BASE_LAYER_ID,
- type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
- metadata=run_input.metadata,
- config=run_input.knowledge,
- )
- )
-
- if run_input.ask_human_config is not None:
- # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
- # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
- # later resumes with deferred_tool_results. Needs the history layer above.
- layers.append(
- RunLayerSpec(
- name=DIFY_ASK_HUMAN_LAYER_ID,
- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=run_input.ask_human_config,
+ config=(run_input.knowledge).model_dump(mode="json"),
)
)
@@ -440,13 +365,13 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=DifyOutputLayerConfig(
- json_schema=run_input.output.json_schema,
- description=run_input.output.description,
- strict=run_input.output.strict,
- ),
+ config=(
+ DifyOutputLayerConfig(
+ json_schema=run_input.output.json_schema,
+ description=run_input.output.description,
+ strict=run_input.output.strict,
+ )
+ ).model_dump(mode="json"),
)
)
@@ -455,8 +380,6 @@ class AgentBackendRunRequestBuilder:
idempotency_key=run_input.idempotency_key,
metadata=run_input.metadata,
session_snapshot=run_input.session_snapshot,
- deferred_tool_results=run_input.deferred_tool_results,
- on_exit=LayerExitSignals(default=ExitIntent.SUSPEND),
)
def build_for_workflow_node(self, run_input: AgentBackendWorkflowNodeRunInput) -> CreateRunRequest:
@@ -465,7 +388,7 @@ class AgentBackendRunRequestBuilder:
Layer graph mirrors the workflow surface: prompts → execution context →
optional shell / config / history → LLM → optional
plugin-direct tools / core-routed tools / knowledge search /
- ask_human / structured output.
+ structured output.
"""
layers: list[RunLayerSpec] = []
agent_soul_prompt = _agent_soul_prompt_for_layer(
@@ -476,9 +399,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=AGENT_SOUL_PROMPT_LAYER_ID,
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "agent_soul"},
- config=PromptLayerConfig(prefix=agent_soul_prompt),
+ config=(PromptConfig(prefix=agent_soul_prompt)).model_dump(mode="json"),
)
)
@@ -486,21 +407,15 @@ class AgentBackendRunRequestBuilder:
[
RunLayerSpec(
name=WORKFLOW_NODE_JOB_PROMPT_LAYER_ID,
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "workflow_node_job"},
- config=PromptLayerConfig(user=run_input.workflow_node_job_prompt),
+ config=(PromptConfig(user=run_input.workflow_node_job_prompt)).model_dump(mode="json"),
),
RunLayerSpec(
name=WORKFLOW_USER_PROMPT_LAYER_ID,
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "workflow_user_prompt"},
- config=PromptLayerConfig(user=run_input.user_prompt),
+ config=(PromptConfig(user=run_input.user_prompt)).model_dump(mode="json"),
),
RunLayerSpec(
name=DIFY_EXECUTION_CONTEXT_LAYER_ID,
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=run_input.execution_context,
+ config=(run_input.execution_context).model_dump(mode="json"),
),
]
)
@@ -510,9 +425,9 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_RUNTIME_LAYER_ID,
- type=DIFY_RUNTIME_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref),
+ config=(DifyRuntimeLayerConfig(backend_binding_ref=run_input.backend_binding_ref)).model_dump(
+ mode="json"
+ ),
)
)
# Sandboxed bash workspace (dify.shell). It enters before config so
@@ -520,10 +435,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_SHELL_LAYER_ID,
- type=DIFY_SHELL_LAYER_TYPE_ID,
- deps=_shell_layer_deps(),
- metadata=run_input.metadata,
- config=run_input.shell_config or DifyShellLayerConfig(),
+ config=(run_input.shell_config or DifyShellLayerConfig()).model_dump(mode="json"),
)
)
@@ -531,10 +443,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_CONFIG_LAYER_ID,
- type=DIFY_CONFIG_LAYER_TYPE_ID,
- deps=_config_layer_deps(),
- metadata=run_input.metadata,
- config=run_input.config_layer_config,
+ config=(run_input.config_layer_config).model_dump(mode="json"),
)
)
@@ -542,8 +451,6 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_AGENT_HISTORY_LAYER_ID,
- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- metadata={**run_input.metadata, "origin": "agent_session_history"},
)
)
@@ -551,31 +458,26 @@ class AgentBackendRunRequestBuilder:
[
RunLayerSpec(
name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
- metadata=run_input.metadata,
- config=DifyPluginLLMLayerConfig(
- plugin_id=run_input.model.plugin_id,
- model_provider=run_input.model.model_provider,
- model=run_input.model.model,
- model_settings=_agent_model_settings(run_input.model.model_settings),
- context_window_tokens=run_input.model.context_window_tokens,
- ),
+ config=(
+ DifyPluginLLMLayerConfig(
+ plugin_id=run_input.model.plugin_id,
+ model_provider=run_input.model.model_provider,
+ model=run_input.model.model,
+ model_settings=_agent_model_settings(run_input.model.model_settings),
+ context_window_tokens=run_input.model.context_window_tokens,
+ )
+ ).model_dump(mode="json"),
),
]
)
if run_input.tools is not None and run_input.tools.tools:
- plugin_tool_deps = {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
- if include_shell:
- plugin_tool_deps["shell"] = DIFY_SHELL_LAYER_ID
layers.append(
RunLayerSpec(
name=DIFY_PLUGIN_TOOLS_LAYER_ID,
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps=plugin_tool_deps,
- metadata=run_input.metadata,
- config=run_input.tools,
+ config=(
+ run_input.tools.model_copy(update={"shell": DIFY_SHELL_LAYER_ID if include_shell else None})
+ ).model_dump(mode="json"),
)
)
@@ -583,10 +485,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_CORE_TOOLS_LAYER_ID,
- type=DIFY_CORE_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
- metadata=run_input.metadata,
- config=run_input.core_tools,
+ config=(run_input.core_tools).model_dump(mode="json"),
)
)
@@ -594,23 +493,7 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_KNOWLEDGE_BASE_LAYER_ID,
- type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
- deps={"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID},
- metadata=run_input.metadata,
- config=run_input.knowledge,
- )
- )
-
- if run_input.ask_human_config is not None:
- # Human-in-the-loop ask_human deferred tool (dify.ask_human). A call ends
- # the run with a deferred_tool_call; the caller pauses (workflow HITL) and
- # later resumes with deferred_tool_results. Needs the history layer above.
- layers.append(
- RunLayerSpec(
- name=DIFY_ASK_HUMAN_LAYER_ID,
- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=run_input.ask_human_config,
+ config=(run_input.knowledge).model_dump(mode="json"),
)
)
@@ -618,13 +501,13 @@ class AgentBackendRunRequestBuilder:
layers.append(
RunLayerSpec(
name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- metadata=run_input.metadata,
- config=DifyOutputLayerConfig(
- json_schema=run_input.output.json_schema,
- description=run_input.output.description,
- strict=run_input.output.strict,
- ),
+ config=(
+ DifyOutputLayerConfig(
+ json_schema=run_input.output.json_schema,
+ description=run_input.output.description,
+ strict=run_input.output.strict,
+ )
+ ).model_dump(mode="json"),
)
)
@@ -633,8 +516,6 @@ class AgentBackendRunRequestBuilder:
idempotency_key=run_input.idempotency_key,
metadata=run_input.metadata,
session_snapshot=run_input.session_snapshot,
- deferred_tool_results=run_input.deferred_tool_results,
- on_exit=LayerExitSignals(default=ExitIntent.SUSPEND),
)
diff --git a/api/controllers/console/app/completion.py b/api/controllers/console/app/completion.py
index 591219459b0..c76e0ec435e 100644
--- a/api/controllers/console/app/completion.py
+++ b/api/controllers/console/app/completion.py
@@ -17,7 +17,6 @@ from controllers.common.schema import register_response_schema_models, register_
from controllers.console import console_ns
from controllers.console.agent.app_helpers import resolve_agent_runtime_app_model
from controllers.console.app.error import (
- AgentSessionConfigurationChangedError,
AppUnavailableError,
CompletionRequestError,
ConversationCompletedError,
@@ -622,10 +621,6 @@ def _raise_agent_stream_error_before_response(response):
if isinstance(response, _ClosableStream):
response.close()
message = error_payload.get("message")
- if error_payload.get("code") == AgentSessionConfigurationChangedError.error_code:
- raise AgentSessionConfigurationChangedError(
- str(message or AgentSessionConfigurationChangedError.description)
- )
raise CompletionRequestError(str(message or "Agent App chat failed."))
return _prepend_stream_chunks(buffered, chunk, iterator)
diff --git a/api/controllers/console/app/error.py b/api/controllers/console/app/error.py
index c2808f149a5..391b25630b8 100644
--- a/api/controllers/console/app/error.py
+++ b/api/controllers/console/app/error.py
@@ -1,7 +1,3 @@
-from core.app.apps.agent_app.errors import (
- AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE,
- AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE,
-)
from libs.exception import BaseHTTPException
@@ -53,12 +49,6 @@ class CompletionRequestError(BaseHTTPException):
code = 400
-class AgentSessionConfigurationChangedError(BaseHTTPException):
- error_code = AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE
- description = AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE
- code = 409
-
-
class AppMoreLikeThisDisabledError(BaseHTTPException):
error_code = "app_more_like_this_disabled"
description = "The 'More like this' feature is disabled. Please refresh your page."
diff --git a/api/core/app/apps/agent_app/app_generator.py b/api/core/app/apps/agent_app/app_generator.py
index 294c18eb6a8..6cb48fa0497 100644
--- a/api/core/app/apps/agent_app/app_generator.py
+++ b/api/core/app/apps/agent_app/app_generator.py
@@ -33,7 +33,6 @@ from core.app.apps.agent_app.app_runner import AgentAppRunner
from core.app.apps.agent_app.errors import (
AgentAppGeneratorError,
AgentAppNotPublishedError,
- AgentSessionSnapshotIncompatibleError,
)
from core.app.apps.agent_app.generate_response_converter import AgentAppGenerateResponseConverter
from core.app.apps.agent_app.runtime_request_builder import AgentAppRuntimeRequestBuilder
@@ -63,7 +62,6 @@ from models.agent import (
AgentConfigVersionKind,
AgentScope,
AgentStatus,
- AgentWorkingResourceStatus,
AgentWorkspaceBinding,
AgentWorkspaceOwnerType,
)
@@ -216,172 +214,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):
)
return AgentAppGenerateResponseConverter.convert(response=response, invoke_from=invoke_from)
- def resume_after_form_submission(
- self,
- *,
- app_model: App,
- user: Account | EndUser,
- conversation_id: str,
- form_id: str,
- invoke_from: InvokeFrom,
- session: Session,
- ) -> None:
- """Resume an Agent App conversation after a submitted ask_human HITL form.
-
- ENG-635: triggered by a background task (not an HTTP request). Runs one
- blocking turn with no user query; the runner threads the human's reply
- into the agent run as deferred_tool_results and the assistant answer is
- persisted to the conversation. Live streaming to a reconnected client is
- out of scope here — the message is persisted and can be re-fetched.
- """
- conversation = ConversationService.get_conversation(
- app_model=app_model, conversation_id=conversation_id, user=user, session=session
- )
- draft_type, draft_id = self._resolve_resume_draft(
- app_model=app_model,
- conversation=conversation,
- user=user,
- form_id=form_id,
- session=session,
- )
- agent, agent_config_id, agent_config_version_kind, agent_soul = self._resolve_agent(
- app_model,
- invoke_from=invoke_from,
- draft_type=draft_type,
- draft_id=draft_id,
- user=user,
- session=session,
- conversation=conversation,
- )
-
- app_model_config = (
- session.get(AppModelConfig, app_model.app_model_config_id) if app_model.app_model_config_id else None
- )
- annotation_reply = load_annotation_reply_config(session, app_model.id) if app_model_config else None
-
- app_config = AgentAppConfigManager.get_app_config(
- app_model=app_model,
- agent_soul=agent_soul,
- annotation_reply=annotation_reply,
- app_model_config=app_model_config,
- conversation=conversation,
- )
- model_conf = ModelConfigConverter.convert(app_config)
- trace_manager = TraceQueueManager(app_model.id, user.id if isinstance(user, Account) else user.session_id)
-
- # ENG-638: the agent backend requires the resume composition's layer
- # names to match the suspended snapshot, which includes the per-turn
- # user-prompt layer. So re-send the original user message (the paused
- # turn's query); the continuation is driven by deferred_tool_results and
- # the restored snapshot, not by re-processing this prompt. A blank prompt
- # would drop the user-prompt layer and fail the snapshot match.
- paused_message = session.scalar(
- select(Message)
- .where(Message.conversation_id == conversation.id, Message.query != "")
- .order_by(Message.created_at.desc())
- .limit(1)
- )
- resume_query = paused_message.query if paused_message and paused_message.query else "(resumed)"
-
- application_generate_entity = AgentAppGenerateEntity(
- task_id=str(uuid.uuid4()),
- app_config=app_config,
- model_conf=model_conf,
- conversation_id=conversation.id,
- # A resume carries no new user inputs; the human's answer is the
- # submitted form, threaded in by the runner as deferred_tool_results.
- # The query re-sends the paused turn's message (see above).
- inputs={},
- query=resume_query,
- files=[],
- parent_message_id=UUID_NIL,
- user_id=user.id,
- stream=False,
- invoke_from=invoke_from,
- extras={"auto_generate_conversation_name": False},
- call_depth=0,
- trace_manager=trace_manager,
- agent_id=agent.id,
- agent_config_snapshot_id=agent_config_id,
- agent_config_version_kind=agent_config_version_kind,
- agent_llm_gateway_enabled=True,
- )
-
- conversation, message = self._init_generate_records(
- application_generate_entity,
- conversation,
- session=session,
- )
-
- queue_manager = MessageBasedAppQueueManager(
- task_id=application_generate_entity.task_id,
- user_id=application_generate_entity.user_id,
- invoke_from=application_generate_entity.invoke_from,
- conversation_id=conversation.id,
- app_mode=conversation.mode,
- message_id=message.id,
- )
-
- context = contextvars.copy_context()
- worker_thread = threading.Thread(
- target=self._generate_worker,
- kwargs={
- "flask_app": current_app._get_current_object(), # type: ignore
- "context": context,
- "application_generate_entity": application_generate_entity,
- "queue_manager": queue_manager,
- "conversation_id": conversation.id,
- "message_id": message.id,
- "user_from": UserFrom.ACCOUNT if isinstance(user, Account) else UserFrom.END_USER,
- # Resume continues a paused agent run; skip input guards (see _generate_worker).
- "is_resume": True,
- },
- )
- worker_thread.start()
-
- # Blocking: drive the chat task pipeline to persist the assistant answer.
- self._handle_response(
- application_generate_entity=application_generate_entity,
- queue_manager=queue_manager,
- conversation=conversation,
- message=message,
- user=user,
- stream=False,
- )
-
- @staticmethod
- def _resolve_resume_draft(
- *,
- app_model: App,
- conversation: Any,
- user: Account | EndUser,
- form_id: str,
- session: Session,
- ) -> tuple[str | None, str | None]:
- if conversation.invoke_from != InvokeFrom.DEBUGGER:
- return None, None
- if not isinstance(user, Account):
- return AgentConfigDraftType.DRAFT.value, None
-
- build_draft = session.scalar(
- select(AgentConfigDraft)
- .join(
- AgentWorkspaceBinding,
- AgentWorkspaceBinding.id == AgentConfigDraft.agent_workspace_binding_id,
- )
- .where(
- AgentConfigDraft.tenant_id == app_model.tenant_id,
- AgentConfigDraft.draft_type == AgentConfigDraftType.DEBUG_BUILD,
- AgentConfigDraft.account_id == user.id,
- AgentWorkspaceBinding.tenant_id == app_model.tenant_id,
- AgentWorkspaceBinding.status == AgentWorkingResourceStatus.ACTIVE,
- AgentWorkspaceBinding.pending_form_id == form_id,
- )
- )
- if build_draft is not None:
- return AgentConfigDraftType.DEBUG_BUILD.value, build_draft.id
- return AgentConfigDraftType.DRAFT.value, None
-
def _generate_worker(
self,
*,
@@ -392,7 +224,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):
conversation_id: str,
message_id: str,
user_from: UserFrom,
- is_resume: bool = False,
) -> None:
from libs.flask_utils import preserve_flask_contexts
@@ -402,46 +233,36 @@ class AgentAppGenerator(MessageBasedAppGenerator):
message = self._get_message(message_id)
app_config = application_generate_entity.app_config
- if is_resume:
- # ENG-638: a resume continues a paused agent run; the human's
- # reply is threaded in by the runner as deferred_tool_results.
- # The query is the replayed paused-turn message, kept only to
- # match the suspended snapshot's layers — it is NOT new
- # end-user input, so input guards must NOT run. Moderation or an
- # annotation match on the replayed query would short-circuit the
- # turn and drop the human reply, stranding the ask_human session.
- query = application_generate_entity.query or ""
- else:
- # Apply app-level input guards (content moderation + annotation
- # reply) before reaching the Agent backend, mirroring the EasyUI
- # chat / agent-chat runners. These can short-circuit the turn.
- with session_factory.get_session_maker().begin() as session:
- app_model = session.get(App, app_config.app_id)
- if app_model is None:
- raise AgentAppGeneratorError("App not found")
- handled, query, annotation_reply = self._run_input_guards(
- session=session,
- application_generate_entity=application_generate_entity,
- app_model=app_model,
- message=message,
- queue_manager=queue_manager,
- )
- if annotation_reply:
- from core.app.apps.agent_app.app_runner import publish_text_answer
- from core.app.entities.queue_entities import QueueAnnotationReplyEvent
-
- queue_manager.publish(
- QueueAnnotationReplyEvent(message_annotation_id=annotation_reply.id),
- PublishFrom.APPLICATION_MANAGER,
- )
- publish_text_answer(
- queue_manager=queue_manager,
- model_name=application_generate_entity.model_conf.model,
- answer=annotation_reply.content,
- user_query=query,
- )
- if handled:
- return
+ # Apply app-level input guards (content moderation + annotation
+ # reply) before reaching the Agent backend, mirroring the EasyUI
+ # chat / agent-chat runners. These can short-circuit the turn.
+ with session_factory.get_session_maker().begin() as session:
+ app_model = session.get(App, app_config.app_id)
+ if app_model is None:
+ raise AgentAppGeneratorError("App not found")
+ handled, query, annotation_reply = self._run_input_guards(
+ session=session,
+ application_generate_entity=application_generate_entity,
+ app_model=app_model,
+ message=message,
+ queue_manager=queue_manager,
+ )
+ if annotation_reply:
+ from core.app.apps.agent_app.app_runner import publish_text_answer
+ from core.app.entities.queue_entities import QueueAnnotationReplyEvent
+
+ queue_manager.publish(
+ QueueAnnotationReplyEvent(message_annotation_id=annotation_reply.id),
+ PublishFrom.APPLICATION_MANAGER,
+ )
+ publish_text_answer(
+ queue_manager=queue_manager,
+ model_name=application_generate_entity.model_conf.model,
+ answer=annotation_reply.content,
+ user_query=query,
+ )
+ if handled:
+ return
dify_context = DifyRunContext(
tenant_id=app_config.tenant_id,
@@ -491,15 +312,6 @@ class AgentAppGenerator(MessageBasedAppGenerator):
)
except GenerateTaskStoppedError:
pass
- except AgentSessionSnapshotIncompatibleError as error:
- logger.info(
- "Agent App session snapshot no longer matches the current composition",
- extra={
- "agent_id": application_generate_entity.agent_id,
- "conversation_id": conversation_id,
- },
- )
- queue_manager.publish_error(error, PublishFrom.APPLICATION_MANAGER)
except Exception as e:
logger.exception("Unknown Error in Agent App generate worker")
queue_manager.publish_error(e, PublishFrom.APPLICATION_MANAGER)
diff --git a/api/core/app/apps/agent_app/app_runner.py b/api/core/app/apps/agent_app/app_runner.py
index f155c07a333..c8315afee5b 100644
--- a/api/core/app/apps/agent_app/app_runner.py
+++ b/api/core/app/apps/agent_app/app_runner.py
@@ -3,7 +3,7 @@
Unlike the legacy ``AgentChatAppRunner`` (which runs an in-process ReAct loop),
this runner delegates to the Agent backend, consumes the streamed event flow,
republishes the assistant answer through the existing EasyUI chat task
-pipeline, and saves the latest Agenton snapshot on the persistent Binding.
+pipeline, and saves the latest module state snapshot on the persistent Binding.
"""
from __future__ import annotations
@@ -15,13 +15,10 @@ from collections.abc import Mapping
from decimal import Decimal
from typing import Any, Literal
-from dify_agent.layers.ask_human import AskHumanToolArgs
-from dify_agent.protocol import DeferredToolResultsPayload
from pydantic import JsonValue
from clients.agent_backend import (
AgentBackendAgentMessageDeltaInternalEvent,
- AgentBackendDeferredToolCallInternalEvent,
AgentBackendError,
AgentBackendInternalEventType,
AgentBackendRunCancelledInternalEvent,
@@ -51,9 +48,6 @@ from core.app.entities.queue_entities import (
QueueLLMChunkEvent,
QueueMessageEndEvent,
)
-from core.repositories.human_input_repository import HumanInputFormRepository, HumanInputFormRepositoryImpl
-from core.workflow.nodes.agent_v2.ask_human_hitl import AskHumanFormBuildError, create_ask_human_form
-from core.workflow.nodes.agent_v2.ask_human_resume import build_deferred_tool_results, resolve_ask_human_form
from extensions.ext_database import db
from graphon.file import File
from graphon.model_runtime.entities.llm_entities import LLMResult, LLMResultChunk, LLMResultChunkDelta, LLMUsage
@@ -664,8 +658,6 @@ class AgentAppRunner:
agent_config_version_kind=AgentConfigVersionKind(agent_config_version_kind),
build_draft_id=build_draft_id,
)
- # ENG-638: if a prior turn paused on ask_human and the form is now answered,
- # resume by threading the human's reply into this run as deferred_tool_results.
stored = self._session_store.load_or_create(scope)
runtime = self._build_runtime(
dify_context=dify_context,
@@ -681,7 +673,6 @@ class AgentAppRunner:
image_detail_config=image_detail_config,
idempotency_key=message_id,
stored=stored,
- message_id=message_id,
)
create_response = self._agent_backend_client.create_run(runtime.request)
@@ -696,23 +687,6 @@ class AgentAppRunner:
binding_id=runtime.binding_id,
)
- if isinstance(terminal, AgentBackendDeferredToolCallInternalEvent):
- # ENG-635: the agent asked a human. End this turn with the question and
- # a conversation-owned HITL form; a form submission resumes the run.
- self._pause_for_ask_human(
- terminal=terminal,
- scope=scope,
- dify_context=dify_context,
- agent_soul=agent_soul,
- conversation_id=conversation_id,
- message_id=message_id,
- model_name=model_name,
- runtime=runtime,
- queue_manager=queue_manager,
- query=query,
- )
- return
-
terminal_usage = None
if isinstance(
terminal,
@@ -810,14 +784,8 @@ class AgentAppRunner:
image_detail_config: ImagePromptMessageContent.DETAIL | None,
idempotency_key: str,
stored: StoredAgentAppSession,
- message_id: str | None,
) -> AgentAppRuntimeRequest:
session_snapshot = stored.session_snapshot
- deferred_tool_results = (
- self._resolve_pending_ask_human(stored=stored, dify_context=dify_context, message_id=message_id)
- if message_id is not None
- else None
- )
return self._request_builder.build(
AgentAppRuntimeBuildContext(
dify_context=dify_context,
@@ -833,99 +801,9 @@ class AgentAppRunner:
binding_id=binding_id,
backend_binding_ref=backend_binding_ref,
session_snapshot=session_snapshot,
- deferred_tool_results=deferred_tool_results,
)
)
- def _pause_for_ask_human(
- self,
- *,
- terminal: AgentBackendDeferredToolCallInternalEvent,
- scope: AgentAppSessionScope,
- dify_context: DifyRunContext,
- agent_soul: AgentSoulConfig,
- conversation_id: str,
- message_id: str,
- model_name: str,
- runtime: AgentAppRuntimeRequest,
- queue_manager: AppQueueManager,
- query: str,
- ) -> None:
- """End the chat turn on a dify.ask_human call: create a conversation-owned
- HITL form, persist the pause correlation, and surface the question."""
- try:
- created = create_ask_human_form(
- deferred_tool_call=terminal.deferred_tool_call,
- # Chat forms have no workflow node; key by the turn's message id.
- node_id=message_id,
- default_node_title="Agent",
- contacts=agent_soul.human.contacts,
- repository=self._build_form_repository(dify_context),
- conversation_id=conversation_id,
- )
- except AskHumanFormBuildError as error:
- raise AgentBackendError(f"Failed to build ask_human form for Agent App chat: {error}") from error
-
- # Persist the snapshot + correlation so a form submission can start the
- # second run with the human's answer (ENG-637/638 columns, conversation owner).
- self._save_session(
- scope=scope,
- binding_id=runtime.binding_id,
- snapshot=terminal.session_snapshot,
- pending_form_id=created.form_id,
- pending_tool_call_id=terminal.deferred_tool_call.tool_call_id,
- )
-
- # The structured form is delivered via the HITL surface(s); the chat turn
- # ends by echoing the agent's question so the conversation reflects the ask.
- self._publish_answer(
- queue_manager=queue_manager,
- model_name=model_name,
- answer=self._ask_human_message(created.args),
- query=query,
- usage=_llm_usage_from_agent_backend(terminal.usage),
- )
-
- def _resolve_pending_ask_human(
- self,
- *,
- stored: StoredAgentAppSession,
- dify_context: DifyRunContext,
- message_id: str,
- ) -> DeferredToolResultsPayload | None:
- """Build deferred_tool_results when a pending ask_human form is answered."""
- if stored.pending_form_id is None or stored.pending_tool_call_id is None:
- return None
- outcome = resolve_ask_human_form(
- form_id=stored.pending_form_id,
- tenant_id=dify_context.tenant_id,
- node_id=message_id,
- )
- if outcome is None or outcome.deferred_result is None:
- # Form missing or still waiting — run a normal turn, no resume.
- return None
- return build_deferred_tool_results(
- tool_call_id=stored.pending_tool_call_id,
- result=outcome.deferred_result,
- )
-
- def _build_form_repository(self, dify_context: DifyRunContext) -> HumanInputFormRepository:
- invoke_source = dify_context.invoke_from.value
- return HumanInputFormRepositoryImpl(
- tenant_id=dify_context.tenant_id,
- app_id=dify_context.app_id,
- workflow_execution_id=None,
- invoke_source=invoke_source,
- submission_actor_id=dify_context.user_id if invoke_source in {"debugger", "explore"} else None,
- )
-
- @staticmethod
- def _ask_human_message(args: AskHumanToolArgs) -> str:
- parts = [args.question]
- if args.markdown:
- parts.append(args.markdown)
- return "\n\n".join(parts)
-
def _consume_stream(
self,
run_id: str,
@@ -1090,25 +968,6 @@ class AgentAppRunner:
exc_info=True,
)
- def _publish_answer(
- self,
- *,
- queue_manager: AppQueueManager,
- model_name: str,
- answer: str,
- query: str | None,
- usage: LLMUsage | None = None,
- ) -> None:
- # MVP: emit the full answer as a single chunk + message-end. The chat
- # task pipeline streams the chunk over SSE and persists the message.
- publish_text_answer(
- queue_manager=queue_manager,
- model_name=model_name,
- answer=answer,
- user_query=query,
- usage=usage,
- )
-
def _publish_terminal_answer(
self,
*,
@@ -1167,16 +1026,12 @@ class AgentAppRunner:
scope: AgentAppSessionScope,
binding_id: str,
snapshot: Any,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
) -> bool:
try:
self._session_store.save_active_snapshot(
scope=scope,
binding_id=binding_id,
snapshot=snapshot,
- pending_form_id=pending_form_id,
- pending_tool_call_id=pending_tool_call_id,
)
return True
except Exception:
diff --git a/api/core/app/apps/agent_app/errors.py b/api/core/app/apps/agent_app/errors.py
index bdcd38abfdf..51b4e77116a 100644
--- a/api/core/app/apps/agent_app/errors.py
+++ b/api/core/app/apps/agent_app/errors.py
@@ -1,24 +1,6 @@
-from core.app.apps.exc import AppGenerateError
-
-AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE = "agent_session_configuration_changed"
-AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE = (
- "The Agent configuration changed after this conversation started. Start a new conversation to continue."
-)
-
-
class AgentAppGeneratorError(ValueError):
"""Raised when an Agent App turn cannot be set up."""
class AgentAppNotPublishedError(AgentAppGeneratorError):
"""Raised when a public Agent App runtime is requested before publish."""
-
-
-class AgentSessionSnapshotIncompatibleError(AppGenerateError):
- """Raised when a retained session snapshot no longer matches the current composition."""
-
- error_code = AGENT_SESSION_CONFIGURATION_CHANGED_ERROR_CODE
- status_code = 409
-
- def __init__(self) -> None:
- super().__init__(AGENT_SESSION_CONFIGURATION_CHANGED_MESSAGE)
diff --git a/api/core/app/apps/agent_app/runtime_request_builder.py b/api/core/app/apps/agent_app/runtime_request_builder.py
index 5f05b0c99d6..cc4a63d45d6 100644
--- a/api/core/app/apps/agent_app/runtime_request_builder.py
+++ b/api/core/app/apps/agent_app/runtime_request_builder.py
@@ -13,7 +13,6 @@ from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Literal, cast
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.layers.execution_context import (
DifyExecutionContextInvokeFrom,
DifyExecutionContextLayerConfig,
@@ -25,7 +24,8 @@ from dify_agent.layers.user_prompt import (
DifyUserPromptFileType,
DifyUserPromptImageConfig,
)
-from dify_agent.protocol import CreateRunRequest, DeferredToolResultsPayload
+from dify_agent.protocol import CreateRunRequest
+from dify_agent.protocol.snapshot import SessionSnapshot
from clients.agent_backend import (
AgentBackendAgentAppRunInput,
@@ -46,7 +46,6 @@ from core.workflow.nodes.agent_v2.dify_tools_builder import (
)
from core.workflow.nodes.agent_v2.runtime_request_builder import (
append_runtime_warnings,
- build_ask_human_layer_config,
build_config_aware_soul_mention_resolver,
build_config_layer_config,
build_knowledge_layer_config,
@@ -59,8 +58,6 @@ from models.agent_config_entities import AgentSoulConfig, AgentSoulToolsConfig
from models.provider_ids import ModelProviderID
from services.agent.prompt_mentions import expand_prompt_mentions
-from .errors import AgentSessionSnapshotIncompatibleError
-
class AgentAppRuntimeRequestBuildError(ValueError):
"""Raised when Agent App state cannot be mapped to a valid run request."""
@@ -87,9 +84,7 @@ class AgentAppRuntimeBuildContext:
files: tuple[File, ...] = ()
image_detail_config: ImagePromptMessageContent.DETAIL | None = None
agent_config_version_kind: Literal["snapshot", "draft", "build_draft"] = "snapshot"
- session_snapshot: CompositorSessionSnapshot | None = None
- # ENG-638: set when resuming a chat turn after a submitted ask_human form.
- deferred_tool_results: DeferredToolResultsPayload | None = None
+ session_snapshot: SessionSnapshot | None = None
@dataclass(frozen=True, slots=True)
@@ -206,16 +201,13 @@ class AgentAppRuntimeRequestBuilder:
core_tools=tool_layers.core_tools,
knowledge=knowledge_config,
config_layer_config=config_layer_config,
- ask_human_config=build_ask_human_layer_config(agent_soul),
include_shell=dify_config.AGENT_SHELL_ENABLED,
shell_config=build_shell_layer_config(agent_soul),
session_snapshot=context.session_snapshot,
- deferred_tool_results=context.deferred_tool_results,
idempotency_key=context.idempotency_key,
metadata=metadata,
)
)
- self._validate_session_snapshot_layers(request)
redacted = cast(dict[str, Any], redact_for_agent_backend_log(request))
return AgentAppRuntimeRequest(
request=request,
@@ -245,24 +237,6 @@ class AgentAppRuntimeRequestBuilder:
for file in files
]
- @staticmethod
- def _validate_session_snapshot_layers(request: CreateRunRequest) -> None:
- """Reject stale snapshots before they reach the Agent backend.
-
- Draft rows are updated in place, so their IDs cannot prove that a
- retained snapshot still belongs to the current composition. Agenton
- requires the ordered layer names to match exactly; enforce the same
- invariant at the API boundary and return a product-level error.
- """
-
- snapshot = request.session_snapshot
- if snapshot is None:
- return
- snapshot_layer_names = tuple(layer.name for layer in snapshot.layers)
- composition_layer_names = tuple(layer.name for layer in request.composition.layers)
- if snapshot_layer_names != composition_layer_names:
- raise AgentSessionSnapshotIncompatibleError()
-
def _build_tool_layers(
self,
*,
diff --git a/api/core/app/apps/agent_app/session_store.py b/api/core/app/apps/agent_app/session_store.py
index 07478da10f1..b1c5110900f 100644
--- a/api/core/app/apps/agent_app/session_store.py
+++ b/api/core/app/apps/agent_app/session_store.py
@@ -4,7 +4,7 @@ from __future__ import annotations
from dataclasses import dataclass
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from sqlalchemy import select
from sqlalchemy.orm import Session
@@ -54,9 +54,7 @@ class StoredAgentAppSession:
binding_id: str
workspace_id: str
backend_binding_ref: str
- session_snapshot: CompositorSessionSnapshot | None
- pending_form_id: str | None = None
- pending_tool_call_id: str | None = None
+ session_snapshot: SessionSnapshot | None
class AgentAppWorkspaceStore:
@@ -141,9 +139,7 @@ class AgentAppWorkspaceStore:
*,
scope: AgentAppSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
+ snapshot: SessionSnapshot | None,
) -> None:
if snapshot is None:
return
@@ -151,25 +147,17 @@ class AgentAppWorkspaceStore:
tenant_id=scope.tenant_id,
binding_id=binding_id,
session_snapshot=snapshot.model_dump_json(),
- pending_form_id=pending_form_id,
- pending_tool_call_id=pending_tool_call_id,
)
@staticmethod
def _stored(scope: AgentAppSessionScope, binding: AgentWorkspaceBinding) -> StoredAgentAppSession:
- snapshot = (
- CompositorSessionSnapshot.model_validate_json(binding.session_snapshot)
- if binding.session_snapshot
- else None
- )
+ snapshot = SessionSnapshot.model_validate_json(binding.session_snapshot) if binding.session_snapshot else None
return StoredAgentAppSession(
scope=scope,
binding_id=binding.id,
workspace_id=binding.workspace_id,
backend_binding_ref=binding.backend_binding_ref,
session_snapshot=snapshot,
- pending_form_id=binding.pending_form_id,
- pending_tool_call_id=binding.pending_tool_call_id,
)
diff --git a/api/core/repositories/human_input_repository.py b/api/core/repositories/human_input_repository.py
index b144d1f88d4..4d35c05e0f9 100644
--- a/api/core/repositories/human_input_repository.py
+++ b/api/core/repositories/human_input_repository.py
@@ -63,9 +63,7 @@ class FormCreateParams:
display_in_ui: bool
resolved_default_values: Mapping[str, Any]
form_kind: HumanInputFormKind = HumanInputFormKind.RUNTIME
- # ENG-635: the conversation this form belongs to. Set together with
- # workflow_execution_id for chatflow runs; set alone (workflow_execution_id None)
- # for Agent v2 chat ask_human forms, which have no workflow run.
+ # Chatflow forms also belong to a conversation.
conversation_id: str | None = None
form_id: str | None = None
@@ -230,8 +228,7 @@ class HumanInputFormRecord:
recipient_id: str | None
recipient_type: RecipientType | None
access_token: str | None
- # ENG-635: Agent v2 chat owner (NULL for workflow-owned forms). Trailing +
- # defaulted so existing record constructions stay source-compatible.
+ # Retain chatflow conversation correlation alongside the workflow run owner.
conversation_id: str | None = None
@property
@@ -450,15 +447,8 @@ class HumanInputFormRepositoryImpl:
if not app_id:
raise ValueError("app_id is required to create a human input form")
workflow_execution_id = params.workflow_execution_id or self._workflow_execution_id
- # A RUNTIME form must be owned by at least one of: a workflow run (workflow /
- # Human-Input / agent node) or a conversation turn (ENG-635: Agent v2 chat
- # ask_human; chatflow runs set both — workflow_run_id and conversation_id).
- if (
- params.form_kind == HumanInputFormKind.RUNTIME
- and workflow_execution_id is None
- and params.conversation_id is None
- ):
- raise ValueError("a runtime human input form requires a workflow_execution_id or conversation_id")
+ if params.form_kind == HumanInputFormKind.RUNTIME and workflow_execution_id is None:
+ raise ValueError("a runtime human input form requires a workflow_execution_id")
with session_factory.create_session() as session, session.begin():
form_id = params.form_id or str(uuidv7())
diff --git a/api/core/workflow/nodes/agent_v2/agent_node.py b/api/core/workflow/nodes/agent_v2/agent_node.py
index 9fd533e5fae..8d5c30a33b1 100644
--- a/api/core/workflow/nodes/agent_v2/agent_node.py
+++ b/api/core/workflow/nodes/agent_v2/agent_node.py
@@ -4,12 +4,11 @@ import logging
from collections.abc import Generator, Mapping, Sequence
from typing import TYPE_CHECKING, Any, override
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.protocol import CancelRunRequest
+from dify_agent.protocol.snapshot import SessionSnapshot
from clients.agent_backend import (
AgentBackendAgentMessageDeltaInternalEvent,
- AgentBackendDeferredToolCallInternalEvent,
AgentBackendError,
AgentBackendHTTPError,
AgentBackendInternalEventType,
@@ -24,11 +23,7 @@ from clients.agent_backend import (
AgentBackendValidationError,
)
from core.app.entities.app_invoke_entities import DIFY_RUN_CONTEXT_KEY, DifyRunContext
-from core.repositories.human_input_repository import HumanInputFormRepository, HumanInputFormRepositoryImpl
-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired
-from core.workflow.nodes.human_input.session_binding import default_session_binding
from core.workflow.system_variables import SystemVariableKey, get_system_text
-from graphon.entities.pause_reason import HitlRequired, SchedulingPause
from graphon.enums import (
BuiltinNodeTypes,
ErrorStrategy,
@@ -40,12 +35,10 @@ from graphon.graph_events import NodeRunPauseRequestedEvent
from graphon.node_events import NodeEventBase, NodeRunResult, StreamCompletedEvent
from graphon.nodes.base.node import Node
from graphon.nodes.base.variable_template_parser import VariableTemplateParser
-from models.agent_config_entities import AgentSoulConfig, WorkflowNodeJobConfig, WorkflowOutputRoutes
+from models.agent_config_entities import WorkflowNodeJobConfig, WorkflowOutputRoutes
from services.agent.prompt_mentions import extract_workflow_node_output_selectors
from services.agent.workspace_service import AgentWorkspaceNotFoundError
-from .ask_human_hitl import AskHumanFormBuildError, build_ask_human_pause_reason
-from .ask_human_resume import build_deferred_tool_results, resolve_ask_human_form
from .binding_resolver import WorkflowAgentBindingError, WorkflowAgentBindingResolver
from .entities import DifyAgentNodeData
from .output_adapter import WorkflowAgentOutputAdapter
@@ -74,10 +67,7 @@ logger = logging.getLogger(__name__)
# Stream + started events are filtered out before we yield; transport errors
# are surfaced as a separate StreamCompletedEvent in the second tuple slot.
type _TerminalAgentBackendEvent = (
- AgentBackendRunSucceededInternalEvent
- | AgentBackendRunFailedInternalEvent
- | AgentBackendRunCancelledInternalEvent
- | AgentBackendDeferredToolCallInternalEvent
+ AgentBackendRunSucceededInternalEvent | AgentBackendRunFailedInternalEvent | AgentBackendRunCancelledInternalEvent
)
@@ -137,16 +127,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
def populate_start_event(self, event) -> None:
event.extras["agent_node"] = {"version": "2", "agent_node_kind": self.node_data.agent_node_kind}
- @staticmethod
- def _to_graph_pause_reason(reason: HumanInputRequired | SchedulingPause) -> HitlRequired | SchedulingPause:
- if isinstance(reason, HumanInputRequired):
- return HitlRequired(
- session_id=default_session_binding.issue_session_id_for_form(form_id=reason.form_id),
- node_id=reason.node_id,
- node_title=reason.node_title,
- )
- return reason
-
@override
def _run(self) -> Generator[NodeEventBase | NodeRunPauseRequestedEvent]:
inputs: dict[str, Any] = {}
@@ -182,8 +162,7 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
self.graph_runtime_state.variable_pool,
SystemVariableKey.WORKFLOW_EXECUTION_ID,
)
- # Set on chatflow (advanced-chat) runs; None for a pure workflow run. Lets an
- # ask_human form be tagged with its conversation in addition to workflow_run_id.
+ # Chatflow sessions also carry their owning conversation.
conversation_id = get_system_text(
self.graph_runtime_state.variable_pool,
SystemVariableKey.CONVERSATION_ID,
@@ -253,40 +232,10 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
custom_outputs = list(node_job.declared_outputs)
outputs_by_name = {output.name: output for output in custom_outputs}
- # ──── ENG-638: resume after a submitted/timed-out ask_human form ────
- # graphon re-executes this _run when the outer workflow resumes. If a
- # pending ask_human form is now terminal, thread the human's answer into
- # the second Agent run as deferred_tool_results; if it is somehow still
- # waiting, re-emit the same pause defensively.
- deferred_tool_results = None
stored_session = self._session_store.load_or_create_node_execution_session(
session_scope,
home_snapshot_id=bundle.snapshot.home_snapshot_id,
)
- if stored_session.pending_form_id is not None:
- resume_outcome = resolve_ask_human_form(
- form_id=stored_session.pending_form_id,
- tenant_id=dify_ctx.tenant_id,
- node_id=self._node_id,
- )
- if resume_outcome is not None and resume_outcome.repause is not None:
- yield self._pause_event(
- reason=resume_outcome.repause,
- inputs=inputs,
- process_data=process_data,
- metadata=metadata,
- )
- return
- if (
- resume_outcome is not None
- and resume_outcome.deferred_result is not None
- and stored_session.pending_tool_call_id is not None
- ):
- deferred_tool_results = build_deferred_tool_results(
- tool_call_id=stored_session.pending_tool_call_id,
- result=resume_outcome.deferred_result,
- )
-
# ──── Retry loop (Stage 4 §7) ────
attempt = 0
while True:
@@ -306,7 +255,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
backend_binding_ref=stored_session.backend_binding_ref,
attempt=attempt,
session_snapshot=stored_session.session_snapshot,
- deferred_tool_results=deferred_tool_results,
)
)
except WorkflowAgentRuntimeRequestBuildError as error:
@@ -386,65 +334,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
)
return
- if isinstance(terminal_event, AgentBackendDeferredToolCallInternalEvent):
- # ENG-636: a dify.ask_human deferred call pauses the *outer*
- # workflow through the existing HITL form path. Any other deferred
- # tool (none today) falls back to a generic scheduling pause. The
- # form is built *before* the snapshot is saved so its id can be
- # persisted as the pause correlation (ENG-637).
- try:
- pause_request = build_ask_human_pause_reason(
- deferred_tool_call=terminal_event.deferred_tool_call,
- node_id=self._node_id,
- default_node_title=bundle.agent.name or self._node_id,
- workflow_run_id=workflow_run_id,
- conversation_id=conversation_id,
- contacts=AgentSoulConfig.model_validate(bundle.snapshot.config_snapshot_dict).human.contacts,
- repository=self._build_human_input_form_repository(
- dify_ctx=dify_ctx, workflow_run_id=workflow_run_id
- ),
- )
- except AskHumanFormBuildError as error:
- yield self._failure_event(
- inputs=inputs,
- process_data=process_data,
- metadata=metadata,
- error=str(error),
- error_type="agent_ask_human_form_build_error",
- )
- return
-
- # ENG-637: persist the awaiting-form id + deferred tool_call id
- # next to the snapshot so the resumed node can rebuild
- # deferred_tool_results from the submitted form.
- pending_form_id: str | None = None
- pending_tool_call_id: str | None = None
- pause_reason: HumanInputRequired | SchedulingPause
- if pause_request is not None:
- pending_form_id = pause_request.form_id
- pending_tool_call_id = terminal_event.deferred_tool_call.tool_call_id
- pause_reason = pause_request
- else:
- pause_reason = SchedulingPause(
- message=terminal_event.message
- or "Agent backend run requested workflow pause for external input."
- )
- self._save_session_snapshot(
- session_scope=session_scope,
- binding_id=stored_session.binding_id,
- snapshot=terminal_event.session_snapshot,
- metadata=metadata,
- pending_form_id=pending_form_id,
- pending_tool_call_id=pending_tool_call_id,
- )
- yield self._pause_event(
- reason=pause_reason,
- inputs=inputs,
- process_data=process_data,
- metadata=metadata,
- )
- return
-
# A failed attempt does not retire the product-owned Binding. The
# Workflow Run terminal lifecycle event owns that transition.
if not isinstance(terminal_event, AgentBackendRunSucceededInternalEvent):
@@ -586,15 +475,12 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
**dict(metadata.get("agent_backend") or {}),
"stream_event_count": stream_event_count,
}
- # Narrow to the known terminal event types before returning
- # to the caller. Deferred-tool events are terminal on the
- # Dify Agent wire, then converted into workflow pause locally.
+ # Narrow to known terminal event types before returning to the caller.
if isinstance(
internal_event,
AgentBackendRunSucceededInternalEvent
| AgentBackendRunFailedInternalEvent
- | AgentBackendRunCancelledInternalEvent
- | AgentBackendDeferredToolCallInternalEvent,
+ | AgentBackendRunCancelledInternalEvent,
):
return internal_event, None
cancellation = self._cancel_backend_run(
@@ -690,44 +576,19 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
],
}
- def _build_human_input_form_repository(
- self,
- *,
- dify_ctx: DifyRunContext,
- workflow_run_id: str | None,
- ) -> HumanInputFormRepository:
- """Construct the existing HITL form repository for ask_human form creation.
-
- Mirrors the Human Input node's repository wiring (``node_runtime``) so the
- ask_human form shares the same delivery/debug/console behavior: a
- submission actor is only attributed for debugger/explore surfaces.
- """
- invoke_source = dify_ctx.invoke_from.value
- return HumanInputFormRepositoryImpl(
- tenant_id=dify_ctx.tenant_id,
- app_id=dify_ctx.app_id,
- workflow_execution_id=workflow_run_id,
- invoke_source=invoke_source,
- submission_actor_id=dify_ctx.user_id if invoke_source in {"debugger", "explore"} else None,
- )
-
def _save_session_snapshot(
self,
*,
session_scope: WorkflowAgentSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
+ snapshot: SessionSnapshot | None,
metadata: dict[str, Any],
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
) -> None:
try:
self._session_store.save_active_snapshot(
scope=session_scope,
binding_id=binding_id,
snapshot=snapshot,
- pending_form_id=pending_form_id,
- pending_tool_call_id=pending_tool_call_id,
)
agent_backend = dict(metadata.get("agent_backend") or {})
agent_backend["session_snapshot_persisted"] = snapshot is not None
@@ -787,27 +648,6 @@ class DifyAgentNode(Node[DifyAgentNodeData]):
)
)
- def _pause_event(
- self,
- *,
- reason: HumanInputRequired | SchedulingPause,
- inputs: dict[str, Any],
- process_data: dict[str, Any],
- metadata: dict[str, Any],
- ) -> NodeRunPauseRequestedEvent:
- return NodeRunPauseRequestedEvent(
- id=self.execution_id,
- node_id=self._node_id,
- node_type=self.node_type,
- node_run_result=NodeRunResult(
- status=WorkflowNodeExecutionStatus.PAUSED,
- inputs=inputs,
- process_data=process_data,
- metadata={WorkflowNodeExecutionMetadataKey.AGENT_LOG: metadata},
- ),
- reason=self._to_graph_pause_reason(reason),
- )
-
@staticmethod
def _agent_backend_error_type(error: AgentBackendError) -> str:
if isinstance(error, AgentBackendValidationError):
diff --git a/api/core/workflow/nodes/agent_v2/ask_human_hitl.py b/api/core/workflow/nodes/agent_v2/ask_human_hitl.py
deleted file mode 100644
index 56b3b59d2ae..00000000000
--- a/api/core/workflow/nodes/agent_v2/ask_human_hitl.py
+++ /dev/null
@@ -1,355 +0,0 @@
-"""Map a ``dify.ask_human`` deferred tool call onto the existing HITL form path.
-
-ENG-636. When an Agent backend run ends with a deferred ``dify.ask_human`` tool
-call, the workflow Agent node pauses the *outer* workflow through the very same
-HITL form path the Human Input node uses — reusing the form repository,
-delivery channels, and submission endpoints unchanged. This module is a pure
-translation layer: model-facing ask_human tool args become graphon form
-entities (``HumanInputNodeData`` / ``FormInputConfig`` / ``UserActionConfig``)
-plus Dify delivery configs and the enriched Dify-side pause reason payload.
-The Graphon ``HitlRequired`` conversion stays at the node boundary.
-
-The agent-side ``dify.ask_human`` contract is richer than the workflow form
-schema in two places, handled here without widening the form vocabulary:
-
-* ask_human fields carry a human label; graphon ``FormInputConfig`` does not.
- Labels are rendered into ``form_content`` next to a ``{{#$output.<name>#}}``
- marker — exactly how the Human Input node positions labelled inputs today.
-* ask_human action ids are valid identifiers of any length; graphon
- ``UserActionConfig.id`` caps ids at 20 chars. Over-long ids are clamped
- deterministically (stable + collision-resistant) so the form always builds;
- the human-visible action *label* is always preserved verbatim.
-"""
-
-from __future__ import annotations
-
-import hashlib
-from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
-from typing import Any, assert_never
-
-from dify_agent.layers.ask_human import (
- AskHumanAction,
- AskHumanField,
- AskHumanFileField,
- AskHumanFileListField,
- AskHumanParagraphField,
- AskHumanSelectField,
- AskHumanToolArgs,
-)
-from dify_agent.protocol import DeferredToolCallPayload
-from pydantic import ValidationError
-
-from core.repositories.human_input_repository import FormCreateParams, HumanInputFormRepository
-from core.workflow.human_input_adapter import (
- DeliveryChannelConfig,
- EmailDeliveryConfig,
- EmailDeliveryMethod,
- EmailRecipients,
- ExternalRecipient,
- InteractiveSurfaceDeliveryMethod,
-)
-from core.workflow.nodes.human_input.entities import (
- FileInputConfig,
- FileListInputConfig,
- FormInputConfig,
- HumanInputNodeData,
- ParagraphInputConfig,
- SelectInputConfig,
- StringListSource,
- StringSource,
- UserActionConfig,
-)
-from core.workflow.nodes.human_input.enums import ButtonStyle, TimeoutUnit, ValueSourceType
-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired
-from models.agent_config_entities import AgentHumanContactConfig
-
-# Default ask_human tool name (see ``DifyAskHumanLayerConfig.tool_name``). The
-# Agent node only knows how to translate this one deferred tool into a form.
-DEFAULT_ASK_HUMAN_TOOL_NAME = "ask_human"
-
-# Graphon ``UserActionConfig.id`` hard-caps identifiers at 20 chars.
-_MAX_ACTION_ID_LEN = 20
-# No timeout lives in the ask_human contract; reuse the Human Input node default.
-_DEFAULT_TIMEOUT_HOURS = 36
-_EMAIL_SUBJECT_MAX_LEN = 120
-
-# ``ButtonStyle`` has no "destructive"; map the ask_human destructive intent onto
-# the closest existing form style rather than extending the HITL vocabulary.
-_ACTION_STYLE_TO_BUTTON: dict[str, ButtonStyle] = {
- "default": ButtonStyle.DEFAULT,
- "primary": ButtonStyle.PRIMARY,
- "destructive": ButtonStyle.ACCENT,
-}
-
-# ask_human permits zero actions (a plain acknowledgement); the form surface
-# needs at least one submit affordance.
-_DEFAULT_SUBMIT_ACTION = UserActionConfig(id="submit", title="Submit", button_style=ButtonStyle.PRIMARY)
-
-
-class AskHumanFormBuildError(ValueError):
- """Raised when ask_human tool args cannot be mapped to a HITL form."""
-
-
-def parse_ask_human_args(raw_args: object) -> AskHumanToolArgs:
- """Validate the raw deferred-tool ``args`` payload into ``AskHumanToolArgs``."""
- if isinstance(raw_args, AskHumanToolArgs):
- return raw_args
- if isinstance(raw_args, Mapping):
- try:
- return AskHumanToolArgs.model_validate(dict(raw_args))
- except ValidationError as error:
- raise AskHumanFormBuildError(f"invalid ask_human args: {error}") from error
- raise AskHumanFormBuildError(f"ask_human args must be a mapping, got {type(raw_args).__name__}")
-
-
-def _clamp_action_id(action_id: str) -> str:
- """Return a stable graphon-safe (<= 20 char) action id.
-
- ask_human ids are already valid identifiers; ids within the limit pass
- through untouched so the resume round-trip returns the model's exact id.
- Over-long ids are truncated with a short content hash to stay deterministic
- and collision-resistant while remaining a valid identifier.
- """
- if len(action_id) <= _MAX_ACTION_ID_LEN:
- return action_id
- digest = hashlib.blake2b(action_id.encode("utf-8"), digest_size=3).hexdigest()
- prefix = action_id[: _MAX_ACTION_ID_LEN - len(digest) - 1]
- return f"{prefix}_{digest}"
-
-
-def _to_form_input(field: AskHumanField) -> FormInputConfig:
- match field:
- case AskHumanParagraphField():
- default = (
- StringSource(type=ValueSourceType.CONSTANT, value=field.default) if field.default is not None else None
- )
- return ParagraphInputConfig(output_variable_name=field.name, default=default)
- case AskHumanSelectField():
- return SelectInputConfig(
- output_variable_name=field.name,
- option_source=StringListSource(
- type=ValueSourceType.CONSTANT,
- value=[option.value for option in field.options],
- ),
- )
- case AskHumanFileField():
- return FileInputConfig(output_variable_name=field.name)
- case AskHumanFileListField():
- return FileListInputConfig(output_variable_name=field.name, number_limits=field.max_files or 0)
- case _: # pragma: no cover - exhaustive over the discriminated union
- assert_never(field)
-
-
-def _to_user_actions(actions: Sequence[AskHumanAction]) -> list[UserActionConfig]:
- if not actions:
- return [_DEFAULT_SUBMIT_ACTION]
- return [
- UserActionConfig(
- id=_clamp_action_id(action.id),
- title=action.label,
- button_style=_ACTION_STYLE_TO_BUTTON.get(action.style, ButtonStyle.DEFAULT),
- )
- for action in actions
- ]
-
-
-def _render_form_content(args: AskHumanToolArgs) -> str:
- """Compose the markdown body, positioning each field's label + input marker.
-
- Graphon ``FormInputConfig`` carries no label, so the field label is written
- into the content next to the ``{{#$output.<name>#}}`` marker that the form
- surface replaces with the live input — identical to the Human Input node.
- """
- blocks: list[str] = []
- if args.title:
- blocks.append(f"## {args.title}")
- blocks.append(args.question)
- if args.markdown:
- blocks.append(args.markdown)
- for field in args.fields:
- label = f"{field.label} *" if field.required else field.label
- blocks.append(f"**{label}**\n\n{{{{#$output.{field.name}#}}}}")
- return "\n\n".join(blocks)
-
-
-def _resolved_default_values(args: AskHumanToolArgs) -> dict[str, Any]:
- """Pre-fill map the form surface reads, keyed by output variable name.
-
- The graphon select input has no default field, so a select default can only
- be conveyed here; paragraph defaults are included for a uniform pre-fill.
- """
- defaults: dict[str, Any] = {}
- for field in args.fields:
- if isinstance(field, AskHumanParagraphField | AskHumanSelectField) and field.default is not None:
- defaults[field.name] = field.default
- return defaults
-
-
-def ask_human_args_to_node_data(args: AskHumanToolArgs, *, node_title: str) -> HumanInputNodeData:
- """Translate validated ask_human args into a synthetic Human Input node config."""
- return HumanInputNodeData(
- title=node_title,
- form_content=_render_form_content(args),
- inputs=[_to_form_input(field) for field in args.fields],
- user_actions=_to_user_actions(args.actions),
- timeout=_DEFAULT_TIMEOUT_HOURS,
- timeout_unit=TimeoutUnit.HOUR,
- )
-
-
-def build_delivery_methods(
- contacts: Sequence[AgentHumanContactConfig],
- *,
- args: AskHumanToolArgs,
-) -> list[DeliveryChannelConfig]:
- """Build form delivery channels: always the interactive surface, plus email to
- the configured human contacts (the recipients chosen in Agent Soul)."""
- methods: list[DeliveryChannelConfig] = [InteractiveSurfaceDeliveryMethod()]
-
- seen: set[str] = set()
- emails: list[str] = []
- for contact in contacts:
- email = (contact.email or "").strip()
- if email and email not in seen:
- seen.add(email)
- emails.append(email)
-
- if emails:
- subject = (args.title or args.question).strip()[:_EMAIL_SUBJECT_MAX_LEN]
- if args.urgency == "high":
- subject = f"[Action needed] {subject}"
- body = f"{args.question}\n\nOpen the request: {EmailDeliveryConfig.URL_PLACEHOLDER}"
- methods.append(
- EmailDeliveryMethod(
- config=EmailDeliveryConfig(
- recipients=EmailRecipients(items=[ExternalRecipient(email=email) for email in emails]),
- subject=subject,
- body=body,
- )
- )
- )
- return methods
-
-
-@dataclass(frozen=True, slots=True)
-class AskHumanFormCreated:
- """A created ask_human HITL form, owner-agnostic (workflow run or conversation)."""
-
- form_id: str
- args: AskHumanToolArgs
- node_data: HumanInputNodeData
- node_title: str
- resolved_default_values: dict[str, Any]
-
-
-def create_ask_human_form(
- *,
- deferred_tool_call: DeferredToolCallPayload,
- node_id: str,
- default_node_title: str,
- contacts: Sequence[AgentHumanContactConfig],
- repository: HumanInputFormRepository,
- workflow_run_id: str | None = None,
- conversation_id: str | None = None,
- display_in_ui: bool = True,
-) -> AskHumanFormCreated:
- """Create a HITL form from an ask_human deferred call (caller verified tool_name).
-
- The form is owned by exactly one of ``workflow_run_id`` (workflow Agent node)
- or ``conversation_id`` (Agent v2 chat). Raises ``AskHumanFormBuildError`` on
- invalid args, a missing owner, or a repository failure.
- """
- if not workflow_run_id and not conversation_id:
- raise AskHumanFormBuildError("an ask_human HITL form requires a workflow_run_id or conversation_id")
-
- args = parse_ask_human_args(deferred_tool_call.args)
- node_title = args.title or default_node_title
- node_data = ask_human_args_to_node_data(args, node_title=node_title)
- resolved_default_values = _resolved_default_values(args)
-
- try:
- form = repository.create_form(
- FormCreateParams(
- workflow_execution_id=workflow_run_id,
- conversation_id=conversation_id,
- node_id=node_id,
- form_config=node_data,
- # No workflow-variable placeholders to resolve — the content is
- # fully model-authored, so rendered == template.
- rendered_content=node_data.form_content,
- delivery_methods=build_delivery_methods(contacts, args=args),
- display_in_ui=display_in_ui,
- resolved_default_values=resolved_default_values,
- )
- )
- except ValueError as error:
- raise AskHumanFormBuildError(f"failed to create ask_human HITL form: {error}") from error
-
- return AskHumanFormCreated(
- form_id=form.id,
- args=args,
- node_data=node_data,
- node_title=node_title,
- resolved_default_values=resolved_default_values,
- )
-
-
-def build_ask_human_pause_reason(
- *,
- deferred_tool_call: DeferredToolCallPayload,
- node_id: str,
- default_node_title: str,
- workflow_run_id: str | None,
- contacts: Sequence[AgentHumanContactConfig],
- repository: HumanInputFormRepository,
- conversation_id: str | None = None,
- expected_tool_name: str = DEFAULT_ASK_HUMAN_TOOL_NAME,
- display_in_ui: bool = True,
-) -> HumanInputRequired | None:
- """Create a workflow HITL form for an ask_human call and return its pause reason.
-
- Returns ``None`` when the deferred call is *not* the ask_human tool, letting
- the caller fall back to a generic scheduling pause. Raises
- ``AskHumanFormBuildError`` when the call is ask_human but its args or the form
- cannot be built — the caller should surface that as a node failure rather
- than a silent, unresumable pause.
- """
- if deferred_tool_call.tool_name != expected_tool_name:
- return None
- if not workflow_run_id:
- raise AskHumanFormBuildError("workflow_run_id is required to create an ask_human HITL form")
-
- created = create_ask_human_form(
- deferred_tool_call=deferred_tool_call,
- node_id=node_id,
- default_node_title=default_node_title,
- contacts=contacts,
- repository=repository,
- workflow_run_id=workflow_run_id,
- # A chatflow agent node also belongs to a conversation; tag the form so it is
- # queryable per conversation. None for a pure workflow run (workflow_run_id only).
- conversation_id=conversation_id,
- display_in_ui=display_in_ui,
- )
- return HumanInputRequired(
- form_id=created.form_id,
- form_content=created.node_data.form_content,
- inputs=list(created.node_data.inputs),
- actions=list(created.node_data.user_actions),
- node_id=node_id,
- node_title=created.node_title,
- resolved_default_values=created.resolved_default_values,
- )
-
-
-__all__ = [
- "DEFAULT_ASK_HUMAN_TOOL_NAME",
- "AskHumanFormBuildError",
- "AskHumanFormCreated",
- "ask_human_args_to_node_data",
- "build_ask_human_pause_reason",
- "build_delivery_methods",
- "create_ask_human_form",
- "parse_ask_human_args",
-]
diff --git a/api/core/workflow/nodes/agent_v2/ask_human_resume.py b/api/core/workflow/nodes/agent_v2/ask_human_resume.py
deleted file mode 100644
index 84d473e2c29..00000000000
--- a/api/core/workflow/nodes/agent_v2/ask_human_resume.py
+++ /dev/null
@@ -1,162 +0,0 @@
-"""Resume an Agent run after a dify.ask_human HITL form reaches a terminal state.
-
-ENG-638. When the outer workflow resumes (the human submitted the form, or it
-timed out), graphon re-executes the Agent node's ``_run``. This module reads the
-correlated HITL form (by ``pending_form_id``) and maps it back into the
-agent-side ``dify.ask_human`` contract so the node can start a *second* Agent run
-that carries the human's answer:
-
-* submitted -> AskHumanToolResult(status="submitted", action, values)
-* timeout -> AskHumanToolResult(status="timeout")
-* expired (global timeout) -> invalid resume state; the workflow must not resume
-* still waiting (defensive: the host resumed us early) -> re-emit the same
- Dify-side ``HumanInputRequired`` pause rebuilt from the stored form definition.
-
-It only *reads* existing HITL form state — it never mutates the form or the HITL
-submission flow. The DB read (``resolve_ask_human_form``) is kept thin so the
-mapping (``map_form_to_outcome``) stays pure and unit-testable.
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass
-
-from dify_agent.layers.ask_human import (
- AskHumanResultStatus,
- AskHumanSelectedAction,
- AskHumanToolResult,
-)
-from dify_agent.protocol import DeferredToolResultsPayload
-from pydantic import JsonValue
-from sqlalchemy import select
-
-from core.db.session_factory import session_factory
-from core.workflow.nodes.human_input.entities import FormDefinition
-from core.workflow.nodes.human_input.enums import HumanInputFormStatus
-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired
-from models.human_input import HumanInputForm
-
-# A WAITING form has not been answered yet. TIMEOUT is resumable through the
-# agent-facing "timeout" result, but EXPIRED is a global timeout and therefore
-# an invalid resume state, matching the ordinary Human Input callback boundary.
-_FORM_STATUS_TO_RESULT: dict[HumanInputFormStatus, AskHumanResultStatus] = {
- HumanInputFormStatus.SUBMITTED: "submitted",
- HumanInputFormStatus.TIMEOUT: "timeout",
-}
-
-
-@dataclass(frozen=True, slots=True)
-class AskHumanResumeOutcome:
- """Result of inspecting a correlated ask_human form on workflow resume.
-
- Exactly one of ``deferred_result`` / ``repause`` is set:
- * ``deferred_result`` — the form reached a terminal state; start the second run.
- * ``repause`` — the form is still waiting; re-emit this pause defensively.
- """
-
- deferred_result: AskHumanToolResult | None = None
- repause: HumanInputRequired | None = None
-
-
-def resolve_ask_human_form(*, form_id: str, tenant_id: str, node_id: str) -> AskHumanResumeOutcome | None:
- """Load the correlated form and map it to a resume outcome.
-
- Returns ``None`` when the form no longer exists (correlation lost) — the
- caller should fall back to a normal (non-resume) Agent run.
- """
- with session_factory.create_session() as session:
- form = session.scalar(
- select(HumanInputForm).where(
- HumanInputForm.id == form_id,
- HumanInputForm.tenant_id == tenant_id,
- )
- )
- if form is None:
- return None
- return map_form_to_outcome(
- status=form.status,
- selected_action_id=form.selected_action_id,
- submitted_data=form.submitted_data,
- rendered_content=form.rendered_content,
- form_definition=form.form_definition,
- form_id=form.id,
- node_id=node_id,
- )
-
-
-def map_form_to_outcome(
- *,
- status: HumanInputFormStatus,
- selected_action_id: str | None,
- submitted_data: str | None,
- rendered_content: str,
- form_definition: str,
- form_id: str,
- node_id: str,
-) -> AskHumanResumeOutcome:
- """Map a terminal (or still-waiting) HITL form to a resume outcome. Pure."""
- definition = FormDefinition.model_validate_json(form_definition)
- if status == HumanInputFormStatus.WAITING:
- return AskHumanResumeOutcome(repause=_rebuild_pause(definition=definition, form_id=form_id, node_id=node_id))
- if status == HumanInputFormStatus.EXPIRED:
- msg = f"cannot resume globally expired ask_human form, form_id={form_id}"
- raise AssertionError(msg)
-
- result_status = _FORM_STATUS_TO_RESULT.get(status, "unavailable")
- if result_status != "submitted":
- return AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status=result_status))
- return AskHumanResumeOutcome(
- deferred_result=AskHumanToolResult(
- status="submitted",
- action=_selected_action(selected_action_id=selected_action_id, definition=definition),
- values=_submitted_values(submitted_data),
- rendered_content=rendered_content,
- )
- )
-
-
-def build_deferred_tool_results(*, tool_call_id: str, result: AskHumanToolResult) -> DeferredToolResultsPayload:
- """Wrap an ask_human result as the deferred-tool-results payload for resume."""
- return DeferredToolResultsPayload(calls={tool_call_id: result.model_dump(mode="json")})
-
-
-def _submitted_values(submitted_data: str | None) -> dict[str, JsonValue]:
- if not submitted_data:
- return {}
- parsed = json.loads(submitted_data)
- if not isinstance(parsed, dict):
- return {}
- return {str(key): value for key, value in parsed.items()}
-
-
-def _selected_action(*, selected_action_id: str | None, definition: FormDefinition) -> AskHumanSelectedAction | None:
- if selected_action_id is None:
- return None
- # The form's user_action title is the verbatim ask_human action label set at
- # form-build time; fall back to the id only if the action is somehow missing.
- label = next(
- (action.title for action in definition.user_actions if action.id == selected_action_id),
- selected_action_id,
- )
- return AskHumanSelectedAction(id=selected_action_id, label=label)
-
-
-def _rebuild_pause(*, definition: FormDefinition, form_id: str, node_id: str) -> HumanInputRequired:
- return HumanInputRequired(
- form_id=form_id,
- form_content=definition.rendered_content or definition.form_content,
- inputs=list(definition.inputs),
- actions=list(definition.user_actions),
- node_id=node_id,
- node_title=definition.node_title or node_id,
- resolved_default_values=dict(definition.default_values),
- )
-
-
-__all__ = [
- "AskHumanResumeOutcome",
- "build_deferred_tool_results",
- "map_form_to_outcome",
- "resolve_ask_human_form",
-]
diff --git a/api/core/workflow/nodes/agent_v2/output_adapter.py b/api/core/workflow/nodes/agent_v2/output_adapter.py
index 9897959e652..051f2670857 100644
--- a/api/core/workflow/nodes/agent_v2/output_adapter.py
+++ b/api/core/workflow/nodes/agent_v2/output_adapter.py
@@ -4,7 +4,6 @@ from collections.abc import Mapping, Sequence
from typing import Any, Protocol
from clients.agent_backend import (
- AgentBackendDeferredToolCallInternalEvent,
AgentBackendInternalEvent,
AgentBackendInternalEventType,
AgentBackendRunCancelledInternalEvent,
@@ -338,7 +337,6 @@ class WorkflowAgentOutputAdapter:
if isinstance(
event,
AgentBackendRunSucceededInternalEvent
- | AgentBackendDeferredToolCallInternalEvent
| AgentBackendRunFailedInternalEvent
| AgentBackendRunCancelledInternalEvent,
):
diff --git a/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py b/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py
index 8456711973c..30df6cecebb 100644
--- a/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py
+++ b/api/core/workflow/nodes/agent_v2/runtime_feature_manifest.py
@@ -17,15 +17,13 @@ SUPPORTED_AGENT_BACKEND_FEATURES = frozenset(
"knowledge",
"env",
"sandbox",
- # ENG-635: human involvement is exposed at runtime as the dify.ask_human
- # deferred tool; a call pauses via the existing HITL form mechanism.
- "human",
}
)
RESERVED_AGENT_BACKEND_FEATURES = frozenset(
{
"memory",
+ "human",
}
)
@@ -54,7 +52,6 @@ def build_runtime_feature_manifest(agent_soul: AgentSoulConfig) -> dict[str, Any
reserved_status["tools.cli_tools"] = "supported_by_shell_bootstrap"
reserved_status["env"] = "supported_by_shell_bootstrap"
reserved_status["sandbox"] = "forwarded_to_shell_layer_config"
- reserved_status["human"] = "supported_by_ask_human_hitl" if agent_soul.human.contacts else "not_configured"
return {
"supported": sorted(SUPPORTED_AGENT_BACKEND_FEATURES),
diff --git a/api/core/workflow/nodes/agent_v2/runtime_request_builder.py b/api/core/workflow/nodes/agent_v2/runtime_request_builder.py
index 11403182af0..0dcdcb35b36 100644
--- a/api/core/workflow/nodes/agent_v2/runtime_request_builder.py
+++ b/api/core/workflow/nodes/agent_v2/runtime_request_builder.py
@@ -5,9 +5,7 @@ from collections.abc import Mapping, Sequence
from dataclasses import dataclass
from typing import Any, Literal, Protocol, assert_never, cast
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.agent_stub.protocol import AgentStubFileMapping
-from dify_agent.layers.ask_human import DifyAskHumanLayerConfig
from dify_agent.layers.config import (
DifyConfigFileConfig,
DifyConfigLayerConfig,
@@ -35,7 +33,8 @@ from dify_agent.layers.shell import (
DifyShellLayerConfig,
DifyShellSecretRefConfig,
)
-from dify_agent.protocol import CreateRunRequest, DeferredToolResultsPayload
+from dify_agent.protocol import CreateRunRequest
+from dify_agent.protocol.snapshot import SessionSnapshot
from pydantic import BaseModel, ValidationError
from sqlalchemy.exc import OperationalError
@@ -138,10 +137,7 @@ class WorkflowAgentRuntimeBuildContext:
# Stage 4 §7 / D-4: 0 for the first run, then incremented per retry. Drives the
# idempotency key so the backend treats each retry as a fresh request.
attempt: int = 0
- session_snapshot: CompositorSessionSnapshot | None = None
- # ENG-638: set when resuming after a submitted ask_human HITL form; threads
- # the human's answer back into the second Agent run keyed by tool_call_id.
- deferred_tool_results: DeferredToolResultsPayload | None = None
+ session_snapshot: SessionSnapshot | None = None
@dataclass(frozen=True, slots=True)
@@ -273,11 +269,9 @@ class WorkflowAgentRuntimeRequestBuilder:
core_tools=tool_layers.core_tools,
knowledge=knowledge_config,
config_layer_config=config_layer_config,
- ask_human_config=build_ask_human_layer_config(agent_soul),
include_shell=dify_config.AGENT_SHELL_ENABLED,
shell_config=build_shell_layer_config(agent_soul),
session_snapshot=context.session_snapshot,
- deferred_tool_results=context.deferred_tool_results,
idempotency_key=self._idempotency_key(context),
metadata=metadata,
)
@@ -853,20 +847,6 @@ def _knowledge_model_config(model: AgentKnowledgeModelConfig | None) -> DifyKnow
)
-def build_ask_human_layer_config(agent_soul: AgentSoulConfig) -> DifyAskHumanLayerConfig | None:
- """Enable the dify.ask_human deferred tool when the soul configures human involvement.
-
- HITL is opt-in: only when at least one human contact is configured does the
- model get the ``ask_human`` tool (recipients for the resulting form come from
- those contacts, ENG-635). Returns ``None`` to leave the tool off entirely.
- The tool/field guardrails use the layer defaults; ``human.tools`` semantics are
- out of scope this round.
- """
- if not agent_soul.human.contacts:
- return None
- return DifyAskHumanLayerConfig()
-
-
def append_runtime_warnings(metadata: dict[str, Any], warnings: list[dict[str, str]]) -> None:
"""Merge build-time warnings into the metadata runtime-support manifest."""
if not warnings:
diff --git a/api/core/workflow/nodes/agent_v2/session_store.py b/api/core/workflow/nodes/agent_v2/session_store.py
index dd5f5117efe..0392ba72729 100644
--- a/api/core/workflow/nodes/agent_v2/session_store.py
+++ b/api/core/workflow/nodes/agent_v2/session_store.py
@@ -6,7 +6,7 @@ import json
import time
from dataclasses import dataclass
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from sqlalchemy import select
from sqlalchemy.orm import Session
@@ -96,9 +96,7 @@ class StoredWorkflowAgentSession:
binding_id: str
workspace_id: str
backend_binding_ref: str
- session_snapshot: CompositorSessionSnapshot | None
- pending_form_id: str | None = None
- pending_tool_call_id: str | None = None
+ session_snapshot: SessionSnapshot | None
class WorkflowAgentWorkspaceStore:
@@ -236,9 +234,7 @@ class WorkflowAgentWorkspaceStore:
*,
scope: WorkflowAgentSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
+ snapshot: SessionSnapshot | None,
) -> None:
if snapshot is None:
return
@@ -246,8 +242,6 @@ class WorkflowAgentWorkspaceStore:
tenant_id=scope.tenant_id,
binding_id=binding_id,
session_snapshot=snapshot.model_dump_json(),
- pending_form_id=pending_form_id,
- pending_tool_call_id=pending_tool_call_id,
)
def retire_workflow_run(self, *, tenant_id: str, app_id: str, workflow_run_id: str) -> list[str]:
@@ -359,19 +353,13 @@ class WorkflowAgentWorkspaceStore:
scope: WorkflowAgentSessionScope,
binding: AgentWorkspaceBinding,
) -> StoredWorkflowAgentSession:
- snapshot = (
- CompositorSessionSnapshot.model_validate_json(binding.session_snapshot)
- if binding.session_snapshot
- else None
- )
+ snapshot = SessionSnapshot.model_validate_json(binding.session_snapshot) if binding.session_snapshot else None
return StoredWorkflowAgentSession(
scope=scope,
binding_id=binding.id,
workspace_id=binding.workspace_id,
backend_binding_ref=binding.backend_binding_ref,
session_snapshot=snapshot,
- pending_form_id=binding.pending_form_id,
- pending_tool_call_id=binding.pending_tool_call_id,
)
diff --git a/api/extensions/ext_celery.py b/api/extensions/ext_celery.py
index a91009b4884..9f7096197d1 100644
--- a/api/extensions/ext_celery.py
+++ b/api/extensions/ext_celery.py
@@ -182,7 +182,6 @@ def init_app(app: DifyApp) -> Celery:
"tasks.install_default_plugins_task", # tenant default plugin installation
"tasks.new_agent_beta_task", # New Agent Beta eligibility checks
"tasks.refresh_billing_vector_space_task", # billing vector-space cache refresh
- "tasks.app_generate.resume_agent_app_task", # ENG-635: Agent v2 chat ask_human resume
"tasks.workflow_run_archive_download_tasks", # workflow-run archive download preparation
]
day = dify_config.CELERY_BEAT_SCHEDULER_TIME
diff --git a/api/models/human_input.py b/api/models/human_input.py
index 7d35cf990c7..99e0e5f65c3 100644
--- a/api/models/human_input.py
+++ b/api/models/human_input.py
@@ -40,12 +40,7 @@ class HumanInputForm(DefaultFieldsMixin, Base):
tenant_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
app_id: Mapped[str] = mapped_column(StringUUID, nullable=False)
workflow_run_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
- # ENG-635: a RUNTIME form is tagged with its owning workflow run and/or its
- # conversation. Workflow / Human-Input / agent-node forms always set
- # workflow_run_id, and ALSO set conversation_id when the run has a conversation
- # (chatflow / advanced-chat). Agent v2 chat ask_human forms set only
- # conversation_id (the new Agent App has no workflow_run_id). At least one is set;
- # resume routing prefers workflow_run_id when both are present.
+ # Chatflow forms retain their conversation for lookup and deletion.
conversation_id: Mapped[str | None] = mapped_column(StringUUID, nullable=True)
form_kind: Mapped[HumanInputFormKind] = mapped_column(
EnumText(HumanInputFormKind),
diff --git a/api/services/agent/workspace_service.py b/api/services/agent/workspace_service.py
index 344f6b38905..3c9a7fc7516 100644
--- a/api/services/agent/workspace_service.py
+++ b/api/services/agent/workspace_service.py
@@ -189,8 +189,6 @@ class AgentWorkspaceService:
tenant_id: str,
binding_id: str,
session_snapshot: str,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
) -> None:
with session_factory.create_session() as session:
binding = session.scalar(
@@ -203,8 +201,6 @@ class AgentWorkspaceService:
if binding is None:
raise AgentWorkspaceNotFoundError("ACTIVE Binding is unavailable")
binding.session_snapshot = session_snapshot
- binding.pending_form_id = pending_form_id
- binding.pending_tool_call_id = pending_tool_call_id
session.commit()
@classmethod
diff --git a/api/services/human_input_service.py b/api/services/human_input_service.py
index 66a1a88c524..416c3a0c5d2 100644
--- a/api/services/human_input_service.py
+++ b/api/services/human_input_service.py
@@ -223,12 +223,9 @@ class HumanInputService:
if result.form_kind != HumanInputFormKind.RUNTIME:
return
- # A RUNTIME form is owned by a workflow run (workflow Agent node) or a
- # conversation (ENG-635: Agent v2 chat). Route the resume accordingly.
+ # Runtime Human Input forms resume their owning workflow run.
if result.workflow_run_id is not None:
self.enqueue_resume(result.workflow_run_id)
- elif result.conversation_id is not None:
- self.enqueue_agent_app_resume(conversation_id=result.conversation_id, form_id=result.form_id)
def ensure_form_active(self, form: Form) -> None:
if form.submitted:
@@ -289,22 +286,6 @@ class HumanInputService:
logger.warning("App mode %s does not support resume for workflow run %s", app.mode, workflow_run_id)
- def enqueue_agent_app_resume(self, *, conversation_id: str, form_id: str) -> None:
- """ENG-635: resume an Agent v2 chat after its ask_human form is submitted.
-
- Enqueues a background turn for the conversation; the Agent App runner
- continues the agent run, threading the human's reply into the request as
- ``deferred_tool_results``.
- """
- from tasks.app_generate.resume_agent_app_task import resume_agent_app_execution
-
- try:
- resume_agent_app_execution.apply_async(
- kwargs={"conversation_id": conversation_id, "form_id": form_id},
- )
- except Exception: # pragma: no cover
- logger.exception("Failed to enqueue Agent App resume for conversation %s form %s", conversation_id, form_id)
-
def _load_variable_pool_for_form(self, form: Form) -> ReadOnlyVariablePool | None:
workflow_run_id = form.workflow_run_id
if workflow_run_id is None:
diff --git a/api/tasks/app_generate/resume_agent_app_task.py b/api/tasks/app_generate/resume_agent_app_task.py
deleted file mode 100644
index eac6d273425..00000000000
--- a/api/tasks/app_generate/resume_agent_app_task.py
+++ /dev/null
@@ -1,78 +0,0 @@
-"""Background resume of an Agent v2 chat after a submitted ask_human HITL form.
-
-ENG-635. When a human submits a conversation-owned ask_human form (delivered via
-email/webapp), ``HumanInputService`` enqueues this task. It reconstructs the
-conversation context and runs one blocking Agent App turn; the runner detects the
-answered form and continues the agent run with the human's reply
-(``deferred_tool_results``), persisting the assistant answer to the conversation.
-"""
-
-from __future__ import annotations
-
-import logging
-
-from celery import shared_task
-
-from core.app.apps.agent_app.app_generator import AgentAppGenerator
-from core.app.entities.app_invoke_entities import InvokeFrom
-from extensions.ext_database import db
-from models.account import Account
-from models.human_input import HumanInputForm
-from models.model import App, Conversation, EndUser
-from tasks.app_generate.workflow_execute_task import WORKFLOW_BASED_APP_EXECUTION_QUEUE
-
-logger = logging.getLogger(__name__)
-
-
-@shared_task(queue=WORKFLOW_BASED_APP_EXECUTION_QUEUE, name="resume_agent_app_execution")
-def resume_agent_app_execution(*, conversation_id: str, form_id: str) -> None:
- form = db.session.get(HumanInputForm, form_id)
- if form is None or form.conversation_id != conversation_id:
- logger.warning("Agent App resume: form %s missing or conversation mismatch", form_id)
- return
-
- app_model = db.session.get(App, form.app_id)
- if app_model is None:
- logger.warning("Agent App resume: app %s not found for form %s", form.app_id, form_id)
- return
-
- conversation = db.session.get(Conversation, conversation_id)
- if conversation is None:
- logger.warning("Agent App resume: conversation %s not found", conversation_id)
- return
-
- user = _resolve_conversation_user(app_model=app_model, conversation=conversation)
- if user is None:
- logger.warning("Agent App resume: no user resolvable for conversation %s", conversation_id)
- return
-
- try:
- AgentAppGenerator().resume_after_form_submission(
- app_model=app_model,
- user=user,
- conversation_id=conversation_id,
- form_id=form_id,
- invoke_from=_resolve_invoke_from(conversation),
- session=db.session(),
- )
- except Exception:
- logger.exception("Agent App resume failed for conversation %s form %s", conversation_id, form_id)
- finally:
- db.session.close()
-
-
-def _resolve_conversation_user(*, app_model: App, conversation: Conversation) -> Account | EndUser | None:
- if conversation.from_account_id:
- account = db.session.get(Account, conversation.from_account_id)
- if account is not None:
- account.set_tenant_id_with_session(app_model.tenant_id, session=db.session())
- return account
- if conversation.from_end_user_id:
- return db.session.get(EndUser, conversation.from_end_user_id)
- return None
-
-
-def _resolve_invoke_from(conversation: Conversation) -> InvokeFrom:
- if conversation.invoke_from is None:
- return InvokeFrom.WEB_APP
- return InvokeFrom.value_of(conversation.invoke_from.value)
diff --git a/api/tasks/human_input_timeout_tasks.py b/api/tasks/human_input_timeout_tasks.py
index 7325602e7d2..acaccf2474c 100644
--- a/api/tasks/human_input_timeout_tasks.py
+++ b/api/tasks/human_input_timeout_tasks.py
@@ -106,17 +106,11 @@ def check_and_handle_human_input_timeouts(limit: int = 100) -> None:
session_factory=session_factory,
)
elif record.workflow_run_id is not None:
- # Workflow Agent node / Human Input node form: resume the workflow.
+ # Human Input node form: resume the workflow.
service.enqueue_resume(record.workflow_run_id)
- elif record.conversation_id is not None:
- # ENG-635: Agent v2 chat ask_human form is conversation-owned (no
- # workflow_run_id). Resume the chat turn so the timeout is threaded
- # back to the agent run as the ask_human deferred_tool_result
- # (status="timeout"), mirroring HumanInputService.submit_form_by_token.
- service.enqueue_agent_app_resume(conversation_id=record.conversation_id, form_id=record.form_id)
else:
logger.warning(
- "Timed-out form %s has neither workflow_run_id nor conversation_id; skipping resume",
+ "Timed-out form %s has no workflow_run_id; skipping resume",
record.form_id,
)
except Exception:
diff --git a/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py b/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py
index 623d06b0258..b4fcc34d578 100644
--- a/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py
+++ b/api/tests/unit_tests/clients/agent_backend/test_event_adapter.py
@@ -1,10 +1,7 @@
from decimal import Decimal
-import pytest
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.protocol import (
AgentRunUsage,
- DeferredToolCallPayload,
PydanticAIStreamRunEvent,
RunCancelledEvent,
RunCancelledEventData,
@@ -15,11 +12,11 @@ from dify_agent.protocol import (
RunSucceededEvent,
RunSucceededEventData,
)
+from dify_agent.protocol.snapshot import SessionSnapshot
from pydantic_ai.messages import FinalResultEvent
from clients.agent_backend import (
AgentBackendAgentMessageDeltaInternalEvent,
- AgentBackendDeferredToolCallInternalEvent,
AgentBackendInternalEventType,
AgentBackendRunCancelledInternalEvent,
AgentBackendRunEventAdapter,
@@ -78,7 +75,7 @@ def test_event_adapter_maps_pydantic_ai_stream_event_agent_message_delta_annotat
def test_event_adapter_maps_run_succeeded_to_final_output():
- snapshot = CompositorSessionSnapshot(layers=[])
+ snapshot = SessionSnapshot(layers={})
adapted = AgentBackendRunEventAdapter().adapt(
RunSucceededEvent(
id="3-0",
@@ -170,102 +167,6 @@ def test_event_adapter_maps_run_failed_to_failed_result():
]
-def test_event_adapter_maps_deferred_tool_call_success_to_internal_event():
- snapshot = CompositorSessionSnapshot(layers=[])
- deferred_tool_call = DeferredToolCallPayload(
- tool_call_id="tool-call-1",
- tool_name="ask_human",
- args={"question": "Need review"},
- metadata={"layer_type": "dify.ask_human", "schema_version": 1},
- )
- adapted = AgentBackendRunEventAdapter().adapt(
- RunSucceededEvent(
- id="5-0",
- run_id="run-1",
- data=RunSucceededEventData(deferred_tool_call=deferred_tool_call, session_snapshot=snapshot),
- )
- )
-
- assert adapted == [
- AgentBackendDeferredToolCallInternalEvent(
- run_id="run-1",
- source_event_id="5-0",
- deferred_tool_call=deferred_tool_call,
- message="Need review",
- session_snapshot=snapshot,
- )
- ]
-
-
-def test_event_adapter_rejects_deferred_tool_call_success_without_payload():
- snapshot = CompositorSessionSnapshot(layers=[])
-
- with pytest.raises(TypeError, match="deferred_tool_call branch is missing payload"):
- _ = AgentBackendRunEventAdapter().adapt(
- RunSucceededEvent(
- id="5-1",
- run_id="run-1",
- data=RunSucceededEventData(deferred_tool_call=None, session_snapshot=snapshot),
- )
- )
-
-
-def test_event_adapter_uses_deferred_tool_call_title_as_pause_message_fallback():
- snapshot = CompositorSessionSnapshot(layers=[])
- deferred_tool_call = DeferredToolCallPayload(
- tool_call_id="tool-call-1",
- tool_name="ask_human",
- args={"title": "Review required"},
- metadata={},
- )
-
- adapted = AgentBackendRunEventAdapter().adapt(
- RunSucceededEvent(
- id="5-2",
- run_id="run-1",
- data=RunSucceededEventData(deferred_tool_call=deferred_tool_call, session_snapshot=snapshot),
- )
- )
-
- assert adapted == [
- AgentBackendDeferredToolCallInternalEvent(
- run_id="run-1",
- source_event_id="5-2",
- deferred_tool_call=deferred_tool_call,
- message="Review required",
- session_snapshot=snapshot,
- )
- ]
-
-
-def test_event_adapter_uses_generic_deferred_tool_call_pause_message_when_args_have_no_label():
- snapshot = CompositorSessionSnapshot(layers=[])
- deferred_tool_call = DeferredToolCallPayload(
- tool_call_id="tool-call-1",
- tool_name="ask_human",
- args={"question": " ", "title": " "},
- metadata={},
- )
-
- adapted = AgentBackendRunEventAdapter().adapt(
- RunSucceededEvent(
- id="5-3",
- run_id="run-1",
- data=RunSucceededEventData(deferred_tool_call=deferred_tool_call, session_snapshot=snapshot),
- )
- )
-
- assert adapted == [
- AgentBackendDeferredToolCallInternalEvent(
- run_id="run-1",
- source_event_id="5-3",
- deferred_tool_call=deferred_tool_call,
- message="Agent backend requested external input via deferred tool 'ask_human'.",
- session_snapshot=snapshot,
- )
- ]
-
-
def test_event_adapter_maps_run_cancelled_to_terminal_cancelled():
adapted = AgentBackendRunEventAdapter().adapt(
RunCancelledEvent(
diff --git a/api/tests/unit_tests/clients/agent_backend/test_fake_client.py b/api/tests/unit_tests/clients/agent_backend/test_fake_client.py
index 6ad82633036..6ed717ef502 100644
--- a/api/tests/unit_tests/clients/agent_backend/test_fake_client.py
+++ b/api/tests/unit_tests/clients/agent_backend/test_fake_client.py
@@ -71,20 +71,6 @@ def test_fake_client_cancel_run_returns_cancelled_status():
assert cancelled.status == "cancelled"
-def test_fake_client_paused_scenario_returns_deferred_tool_call_success_event():
- """The API pause scenario follows the Dify Agent deferred-tool wire shape."""
- client = FakeAgentBackendRunClient(scenario=FakeAgentBackendScenario.PAUSED)
-
- status = client.wait_run("fake-run-1")
- events = list(client.stream_events("fake-run-1"))
-
- assert status.status == "succeeded"
- assert status.error is None
- assert events[-1].type == "run_succeeded"
- assert events[-1].data.deferred_tool_call is not None
- assert events[-1].data.deferred_tool_call.tool_name == "ask_human"
-
-
def test_fake_client_success_wait_run_returns_succeeded_status():
"""Covers the default SUCCESS branch of ``wait_run`` directly."""
status = FakeAgentBackendRunClient().wait_run("fake-run-1")
diff --git a/api/tests/unit_tests/clients/agent_backend/test_request_builder.py b/api/tests/unit_tests/clients/agent_backend/test_request_builder.py
index 29771083de6..c1da744b4b3 100644
--- a/api/tests/unit_tests/clients/agent_backend/test_request_builder.py
+++ b/api/tests/unit_tests/clients/agent_backend/test_request_builder.py
@@ -1,30 +1,13 @@
from typing import Any, cast
import pytest
-from agenton.layers import ExitIntent
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
-from dify_agent.layers.dify_core_tools import (
- DIFY_CORE_TOOLS_LAYER_TYPE_ID,
- DifyCoreToolConfig,
- DifyCoreToolsLayerConfig,
-)
-from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- DifyPluginLLMLayerConfig,
- DifyPluginToolConfig,
- DifyPluginToolsLayerConfig,
-)
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.knowledge import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID
-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellEnvVarConfig, DifyShellLayerConfig
-from dify_agent.layers.user_prompt import (
- DIFY_USER_PROMPT_LAYER_TYPE_ID,
- DifyUserPromptDownloadConfig,
- DifyUserPromptImageConfig,
-)
+from dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfig
+from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig, DifyPluginToolConfig, DifyPluginToolsLayerConfig
+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
+from dify_agent.layers.knowledge import DifyKnowledgeBaseLayerConfig
+from dify_agent.layers.prompt import Config as PromptConfig
+from dify_agent.layers.shell import DifyShellEnvVarConfig, DifyShellLayerConfig
+from dify_agent.layers.user_prompt import DifyUserPromptDownloadConfig, DifyUserPromptImageConfig
from dify_agent.protocol import (
DIFY_AGENT_HISTORY_LAYER_ID,
DIFY_AGENT_MODEL_LAYER_ID,
@@ -99,7 +82,6 @@ def test_request_builder_outputs_dify_agent_create_run_request():
DIFY_AGENT_MODEL_LAYER_ID,
DIFY_AGENT_OUTPUT_LAYER_ID,
]
- assert request.on_exit.default is ExitIntent.SUSPEND
assert request.idempotency_key == "workflow-run-1:node-execution-1"
assert request.metadata == {"workflow_id": "workflow-1", "node_id": "node-1"}
assert "purpose" not in dumped
@@ -109,11 +91,6 @@ def test_request_builder_separates_agent_soul_and_workflow_job_prompt():
request = AgentBackendRunRequestBuilder().build_for_workflow_node(_run_input())
layers = {layer.name: layer for layer in request.composition.layers}
- assert layers[AGENT_SOUL_PROMPT_LAYER_ID].type == PLAIN_PROMPT_LAYER_TYPE_ID
- assert layers[AGENT_SOUL_PROMPT_LAYER_ID].metadata["origin"] == "agent_soul"
- assert layers[WORKFLOW_NODE_JOB_PROMPT_LAYER_ID].metadata["origin"] == "workflow_node_job"
- assert layers[WORKFLOW_USER_PROMPT_LAYER_ID].metadata["origin"] == "workflow_user_prompt"
-
dumped = request.model_dump(mode="json")
assert dumped["composition"]["layers"][0]["config"]["prefix"] == "You are a careful reviewer."
workflow_job_config = dumped["composition"]["layers"][1]["config"]
@@ -136,7 +113,7 @@ def test_request_builder_forwards_plugin_specific_model_settings_via_extra_body(
request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- model_config = cast(DifyPluginLLMLayerConfig, layers[DIFY_AGENT_MODEL_LAYER_ID].config)
+ model_config = DifyPluginLLMLayerConfig.model_validate(layers[DIFY_AGENT_MODEL_LAYER_ID].config)
assert model_config.model_settings == {
"temperature": 0.7,
@@ -159,7 +136,7 @@ def test_agent_app_request_builder_keeps_agent_soul_prompt_for_snapshot_and_draf
request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
assert prompt_config.prefix == original_prompt
@@ -175,7 +152,7 @@ def test_agent_app_request_builder_wraps_agent_soul_prompt_for_build_draft():
request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
assert prompt_config.prefix != original_prompt
assert prompt_config.prefix.startswith("You are running in build mode.")
assert "```text\nYou are Iris.\n```" in prompt_config.prefix
@@ -192,7 +169,7 @@ def test_agent_app_request_builder_uses_longer_fence_for_build_draft_prompt_body
request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
assert "````text" in prompt_config.prefix
assert "```python" in prompt_config.prefix
@@ -201,19 +178,17 @@ def test_request_builder_sets_model_and_output_layer_contract_ids():
request = AgentBackendRunRequestBuilder().build_for_workflow_node(_run_input())
layers = {layer.name: layer for layer in request.composition.layers}
- assert layers[DIFY_EXECUTION_CONTEXT_LAYER_ID].type == DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID
- execution_context_config = cast(DifyExecutionContextLayerConfig, layers[DIFY_EXECUTION_CONTEXT_LAYER_ID].config)
+ execution_context_config = DifyExecutionContextLayerConfig.model_validate(
+ layers[DIFY_EXECUTION_CONTEXT_LAYER_ID].config
+ )
assert execution_context_config.user_id == "user-1"
assert execution_context_config.user_from == "account"
assert execution_context_config.agent_mode == "workflow_run"
assert execution_context_config.invoke_from == "debugger"
- assert layers[DIFY_AGENT_HISTORY_LAYER_ID].type == PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
- assert layers[DIFY_AGENT_MODEL_LAYER_ID].type == DIFY_PLUGIN_LLM_LAYER_TYPE_ID
- model_config = cast(DifyPluginLLMLayerConfig, layers[DIFY_AGENT_MODEL_LAYER_ID].config)
+ model_config = DifyPluginLLMLayerConfig.model_validate(layers[DIFY_AGENT_MODEL_LAYER_ID].config)
assert model_config.plugin_id == "langgenius/openai"
assert "credentials" not in model_config.model_dump(mode="json")
- assert layers[DIFY_AGENT_MODEL_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
- assert layers[DIFY_AGENT_OUTPUT_LAYER_ID].type == DIFY_OUTPUT_LAYER_TYPE_ID
+ assert layers[DIFY_AGENT_MODEL_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
def test_request_builder_adds_dify_plugin_tools_layer_when_configured():
@@ -238,9 +213,8 @@ def test_request_builder_adds_dify_plugin_tools_layer_when_configured():
request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID].type == DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID
- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
- tools_config = cast(DifyPluginToolsLayerConfig, layers[DIFY_PLUGIN_TOOLS_LAYER_ID].config)
+ assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ tools_config = DifyPluginToolsLayerConfig.model_validate(layers[DIFY_PLUGIN_TOOLS_LAYER_ID].config)
assert tools_config.tools[0].tool_name == "current_time"
@@ -264,8 +238,7 @@ def test_request_builder_adds_dify_core_tools_layer_when_configured():
request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- assert layers[DIFY_CORE_TOOLS_LAYER_ID].type == DIFY_CORE_TOOLS_LAYER_TYPE_ID
- assert layers[DIFY_CORE_TOOLS_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
+ assert layers[DIFY_CORE_TOOLS_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
def test_request_builder_adds_knowledge_layer_when_configured():
@@ -288,9 +261,8 @@ def test_request_builder_adds_knowledge_layer_when_configured():
layers = {layer.name: layer for layer in request.composition.layers}
assert DIFY_KNOWLEDGE_BASE_LAYER_ID in layers
- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].type == DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID
- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
- knowledge_config = cast(DifyKnowledgeBaseLayerConfig, layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)
+ assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ knowledge_config = DifyKnowledgeBaseLayerConfig.model_validate(layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)
assert knowledge_config.sets[0].dataset_ids == ["dataset-1"]
@@ -359,11 +331,11 @@ def test_workflow_request_builder_adds_shell_layer_when_include_shell():
assert DIFY_SHELL_LAYER_ID in layers
shell = layers[DIFY_SHELL_LAYER_ID]
- assert shell.type == DIFY_SHELL_LAYER_TYPE_ID
# The shell layer depends on execution_context so the agent server can mint
# per-command Agent Stub env for sandbox CLI forwarding.
- assert shell.deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID, "runtime": "runtime"}
- shell_config = cast(DifyShellLayerConfig, shell.config)
+ assert shell.config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ assert shell.config["runtime"] == "runtime"
+ shell_config = DifyShellLayerConfig.model_validate(shell.config)
assert shell_config.env[0].name == "PROJECT_NAME"
@@ -390,14 +362,13 @@ def test_agent_app_request_builder_emits_multimodal_user_prompt_layer():
request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)
layer = next(layer for layer in request.composition.layers if layer.name == "agent_app_user_prompt")
- assert layer.type == DIFY_USER_PROMPT_LAYER_TYPE_ID
- assert layer.config.text == "List files."
- assert layer.config.files == run_input.user_files
+ assert layer.config["text"] == "List files."
+ assert layer.config["files"] == [f.model_dump(mode="json") for f in run_input.user_files]
restored_request = CreateRunRequest.model_validate_json(request.model_dump_json())
restored_layer = next(
layer for layer in restored_request.composition.layers if layer.name == "agent_app_user_prompt"
)
- assert restored_layer.config == layer.config.model_dump(mode="json")
+ assert restored_layer.config == layer.config
assert "locators" not in restored_layer.config
@@ -438,7 +409,7 @@ def test_agent_app_request_builder_keeps_build_draft_prompt_when_agent_soul_prom
request = AgentBackendRunRequestBuilder().build_for_agent_app(run_input)
layers = {layer.name: layer for layer in request.composition.layers}
- prompt_config = cast(PromptLayerConfig, layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
+ prompt_config = PromptConfig.model_validate(layers[AGENT_SOUL_PROMPT_LAYER_ID].config)
assert "You are running in build mode." in prompt_config.prefix
assert "No task prompt was provided." in prompt_config.prefix
@@ -451,12 +422,9 @@ def test_agent_app_request_builder_adds_shell_layer_when_include_shell():
layers = {layer.name: layer for layer in request.composition.layers}
assert DIFY_SHELL_LAYER_ID in layers
- assert layers[DIFY_SHELL_LAYER_ID].type == DIFY_SHELL_LAYER_TYPE_ID
- assert layers[DIFY_SHELL_LAYER_ID].deps == {
- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,
- "runtime": "runtime",
- }
- shell_config = cast(DifyShellLayerConfig, layers[DIFY_SHELL_LAYER_ID].config)
+ assert layers[DIFY_SHELL_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ assert layers[DIFY_SHELL_LAYER_ID].config["runtime"] == "runtime"
+ shell_config = DifyShellLayerConfig.model_validate(layers[DIFY_SHELL_LAYER_ID].config)
assert shell_config.env[0].name == "APP_ENV"
@@ -480,52 +448,6 @@ def test_agent_app_request_builder_adds_knowledge_layer_when_configured():
layers = {layer.name: layer for layer in request.composition.layers}
assert DIFY_KNOWLEDGE_BASE_LAYER_ID in layers
- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].type == DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID
- assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].deps == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
- knowledge_config = cast(DifyKnowledgeBaseLayerConfig, layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)
+ assert layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ knowledge_config = DifyKnowledgeBaseLayerConfig.model_validate(layers[DIFY_KNOWLEDGE_BASE_LAYER_ID].config)
assert knowledge_config.sets[0].dataset_ids == ["dataset-1", "dataset-2"]
-
-
-# ── ENG-635 / ENG-638: ask_human layer injection + deferred_tool_results ─────
-
-
-def test_ask_human_layer_injected_when_configured():
- from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
-
- from clients.agent_backend.request_builder import DIFY_ASK_HUMAN_LAYER_ID
-
- run_input = _run_input().model_copy(update={"ask_human_config": DifyAskHumanLayerConfig()})
- request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)
-
- layers = {layer.name: layer for layer in request.composition.layers}
- assert DIFY_ASK_HUMAN_LAYER_ID in layers
- assert layers[DIFY_ASK_HUMAN_LAYER_ID].type == DIFY_ASK_HUMAN_LAYER_TYPE_ID
- # the deferred tool needs the history layer to resume, so history must precede it
- names = [layer.name for layer in request.composition.layers]
- assert names.index(DIFY_AGENT_HISTORY_LAYER_ID) < names.index(DIFY_ASK_HUMAN_LAYER_ID)
-
-
-def test_no_ask_human_layer_when_unconfigured():
- from clients.agent_backend.request_builder import DIFY_ASK_HUMAN_LAYER_ID
-
- request = AgentBackendRunRequestBuilder().build_for_workflow_node(_run_input())
- assert all(layer.name != DIFY_ASK_HUMAN_LAYER_ID for layer in request.composition.layers)
-
-
-def test_deferred_tool_results_threaded_into_request():
- from dify_agent.protocol import DeferredToolResultsPayload
-
- payload = DeferredToolResultsPayload(
- calls={
- "tool-call-1": {
- "status": "submitted",
- "action": {"id": "submit", "label": "Submit"},
- "values": {"x": "y"},
- }
- }
- )
- run_input = _run_input().model_copy(update={"deferred_tool_results": payload})
- request = AgentBackendRunRequestBuilder().build_for_workflow_node(run_input)
-
- assert request.deferred_tool_results is not None
- assert "tool-call-1" in request.deferred_tool_results.calls
diff --git a/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py b/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py
index 2e2eae45a68..cb71e5ebea7 100644
--- a/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py
+++ b/api/tests/unit_tests/controllers/console/agent/test_agent_controllers.py
@@ -54,7 +54,7 @@ from controllers.console.agent.roster import (
from controllers.console.app import completion as completion_controller
from controllers.console.app import message as message_controller
from controllers.console.app.completion import AgentBuildChatFinalizeApi, AgentChatMessageApi, AgentChatMessageStopApi
-from controllers.console.app.error import AgentSessionConfigurationChangedError, CompletionRequestError
+from controllers.console.app.error import CompletionRequestError
from controllers.console.app.message import (
AgentChatMessageListApi,
AgentMessageApi,
@@ -1754,39 +1754,6 @@ def test_agent_chat_stream_preflight_raises_first_error_event() -> None:
assert stream.closed is True
-def test_agent_chat_stream_preflight_preserves_session_configuration_error() -> None:
- class ClosableStream:
- def __init__(self) -> None:
- self.closed = False
- self._chunks = iter(
- [
- "event: ping\n\n",
- (
- 'data: {"event":"error","message":"Start a new conversation to continue.",'
- '"code":"agent_session_configuration_changed","status":409}\n\n'
- ),
- ]
- )
-
- def __iter__(self) -> Self:
- return self
-
- def __next__(self) -> str:
- return next(self._chunks)
-
- def close(self) -> None:
- self.closed = True
-
- stream = ClosableStream()
- with pytest.raises(AgentSessionConfigurationChangedError) as exc_info:
- completion_controller._raise_agent_stream_error_before_response(stream)
- assert exc_info.value.code == 409
- assert exc_info.value.error_code == "agent_session_configuration_changed"
- assert exc_info.value.description is not None
- assert "Start a new conversation" in exc_info.value.description
- assert stream.closed is True
-
-
def test_agent_chat_stream_preflight_preserves_first_normal_event() -> None:
stream = iter(
["event: ping\n\n", 'data: {"event":"message","answer":"hello"}\n\n', 'data: {"event":"message_end"}\n\n']
diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py b/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py
index 93d9a182aa3..a4e2cc02ac4 100644
--- a/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py
+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_app_generator.py
@@ -24,7 +24,6 @@ from core.app.apps.agent_app.app_generator import (
AgentAppGenerator,
AgentAppGeneratorError,
)
-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleError
from core.app.apps.exc import GenerateTaskStoppedError
from core.app.entities.app_invoke_entities import InvokeFrom, UserFrom
from core.app.entities.queue_entities import QueueAnnotationReplyEvent
@@ -381,7 +380,6 @@ class TestGenerateWorker:
mocker: MockerFixture,
queue_manager,
*,
- is_resume=False,
query="query",
session_scope_config_version_id="s",
files=(),
@@ -404,7 +402,6 @@ class TestGenerateWorker:
conversation_id="conv",
message_id="msg",
user_from=UserFrom.END_USER,
- is_resume=is_resume,
)
def test_happy_path_runs_backend(self, generator: AgentAppGenerator, mocker: MockerFixture):
@@ -480,20 +477,6 @@ class TestGenerateWorker:
assert events == ["commit", "publish"]
runner.run.assert_not_called()
- def test_resume_skips_input_guards_and_consumes_reply(self, generator, mocker: MockerFixture):
- # ENG-638 (review): on resume the replayed query is NOT new end-user input.
- # Input guards must be skipped, even if moderation/annotation would match,
- # so the run continues and the human reply (deferred_tool_results) is used.
- runner, _ = self._wire(generator, mocker, handled=True) # guards WOULD short-circuit
- queue_manager = mocker.MagicMock()
-
- self._call(generator, mocker, queue_manager, is_resume=True, query="the approved reply")
-
- generator._run_input_guards.assert_not_called()
- runner.run.assert_called_once()
- # the replayed paused-turn query flows straight to the runner (snapshot match)
- assert runner.run.call_args.kwargs["query"] == "the approved reply"
-
def test_generate_task_stopped_is_swallowed(self, generator, mocker: MockerFixture):
self._wire(generator, mocker, run_side_effect=GenerateTaskStoppedError())
queue_manager = mocker.MagicMock()
@@ -505,123 +488,3 @@ class TestGenerateWorker:
queue_manager = mocker.MagicMock()
self._call(generator, mocker, queue_manager)
assert queue_manager.publish_error.called
-
- def test_session_configuration_change_is_published_without_unknown_error_log(
- self,
- generator: AgentAppGenerator,
- mocker: MockerFixture,
- ) -> None:
- error = AgentSessionSnapshotIncompatibleError()
- self._wire(generator, mocker, run_side_effect=error)
- queue_manager = mocker.MagicMock()
- info_log = mocker.patch(f"{MODULE}.logger.info")
- exception_log = mocker.patch(f"{MODULE}.logger.exception")
-
- self._call(generator, mocker, queue_manager)
-
- queue_manager.publish_error.assert_called_once_with(error, module.PublishFrom.APPLICATION_MANAGER)
- info_log.assert_called_once()
- exception_log.assert_not_called()
-
-
-class TestResumeAfterFormSubmission:
- """ENG-638: a resume turn re-sends the paused turn's original query so the
- composition's user-prompt layer matches the suspended snapshot (never blank)."""
-
- def _wire(self, generator, mocker: MockerFixture):
- generator._resolve_agent = mocker.MagicMock(return_value=(_agent(), "snap1", "draft", AgentSoulConfig()))
- generator._init_generate_records = mocker.MagicMock(return_value=(_conversation(), _message()))
- generator._handle_response = mocker.MagicMock(return_value=None)
- get_conversation = mocker.patch(
- f"{MODULE}.ConversationService.get_conversation",
- return_value=_conversation(),
- )
- mocker.patch(f"{MODULE}.AgentAppConfigManager.get_app_config", return_value=mocker.MagicMock(variables=[]))
- mocker.patch(f"{MODULE}.load_annotation_reply_config", return_value={"enabled": False})
- mocker.patch(f"{MODULE}.ModelConfigConverter.convert", return_value=mocker.MagicMock())
- mocker.patch(f"{MODULE}.TraceQueueManager", return_value=mocker.MagicMock())
- mocker.patch(f"{MODULE}.MessageBasedAppQueueManager", return_value=mocker.MagicMock())
- mocker.patch(f"{MODULE}.threading.Thread", return_value=mocker.MagicMock())
- generator._resolve_resume_draft = mocker.MagicMock(return_value=(None, None))
- return (
- mocker.patch(
- f"{MODULE}.AgentAppGenerateEntity", return_value=mocker.MagicMock(task_id="t", user_id="user")
- ),
- get_conversation,
- )
-
- def test_resume_resends_paused_turn_query(self, generator, mocker: MockerFixture):
- entity, get_conversation = self._wire(generator, mocker)
- session = _session()
- config = AppModelConfig(app_id="app1")
- config.id = "config-1"
- session.add_all([config, _conversation(), _message(query="original question")])
- session.commit()
- app_model = _app(app_model_config_id=config.id)
- user = _account()
-
- generator.resume_after_form_submission(
- app_model=app_model,
- user=user,
- conversation_id="conv",
- form_id="form-1",
- invoke_from=InvokeFrom.WEB_APP,
- session=session,
- )
-
- # The paused turn's query is re-sent verbatim — never blank.
- assert entity.call_args.kwargs["query"] == "original question"
- assert "agent_runtime_exit_intent" not in entity.call_args.kwargs
- get_conversation.assert_called_once_with(
- app_model=app_model,
- conversation_id="conv",
- user=user,
- session=session,
- )
- assert generator._init_generate_records.call_args.kwargs["session"] is session
- assert session.get(AppModelConfig, "config-1") is config
- assert generator._resolve_agent.call_args.kwargs["session"] is session
-
- def test_resume_falls_back_to_placeholder_when_no_paused_message(self, generator, mocker: MockerFixture):
- entity, _ = self._wire(generator, mocker)
- session = _session()
-
- generator.resume_after_form_submission(
- app_model=_app(),
- user=_account(),
- conversation_id="conv",
- form_id="form-1",
- invoke_from=InvokeFrom.WEB_APP,
- session=session,
- )
-
- # No prior user message -> a non-blank placeholder, still never blank.
- assert entity.call_args.kwargs["query"] == "(resumed)"
-
- def test_resume_uses_build_draft_for_debugger_conversation(self, generator, mocker: MockerFixture):
- self._wire(generator, mocker)
- conversation = _conversation(invoke_from=InvokeFrom.DEBUGGER)
- mocker.patch(f"{MODULE}.ConversationService.get_conversation", return_value=conversation)
- generator._resolve_resume_draft.return_value = ("debug_build", "draft-build-1")
- account_user = Account(name="Test Account", email="[email protected]")
- account_user.id = "user"
- session = _session()
- config = AppModelConfig(app_id="app1")
- config.id = "config-1"
- session.add_all([config, conversation, _message(query="original question")])
- session.commit()
- app_model = _app(app_model_config_id=config.id)
-
- generator.resume_after_form_submission(
- app_model=app_model,
- user=account_user,
- conversation_id="conv",
- form_id="form-1",
- invoke_from=InvokeFrom.DEBUGGER,
- session=session,
- )
-
- assert generator._resolve_agent.call_args.kwargs["draft_type"] == "debug_build"
- assert generator._resolve_agent.call_args.kwargs["draft_id"] == "draft-build-1"
- assert generator._resolve_agent.call_args.kwargs["session"] is session
- assert generator._resolve_agent.call_args.kwargs["conversation"] is conversation
diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py b/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py
index 1099a252dea..78f060d9df5 100644
--- a/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py
+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_app_runner.py
@@ -12,9 +12,6 @@ from typing import Any, override
from unittest.mock import MagicMock
import pytest
-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot
-from agenton.layers import LifecycleState
-from dify_agent.layers.ask_human import AskHumanToolResult
from dify_agent.protocol import (
AgentRunUsage,
CancelRunRequest,
@@ -30,6 +27,7 @@ from dify_agent.protocol import (
RunSucceededEvent,
RunSucceededEventData,
)
+from dify_agent.protocol.snapshot import SessionSnapshot
from pydantic_ai.messages import (
FunctionToolCallEvent,
FunctionToolResultEvent,
@@ -53,7 +51,6 @@ from clients.agent_backend import (
)
from core.app.apps.agent_app import app_runner as app_runner_module
from core.app.apps.agent_app.app_runner import AgentAppRunner
-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleError
from core.app.apps.agent_app.runtime_request_builder import AgentAppRuntimeBuildContext, AgentAppRuntimeRequestBuilder
from core.app.apps.agent_app.session_store import AgentAppSessionScope, StoredAgentAppSession
from core.app.apps.exc import GenerateTaskStoppedError
@@ -64,7 +61,6 @@ from core.app.entities.queue_entities import (
QueueLLMChunkEvent,
QueueMessageEndEvent,
)
-from core.workflow.nodes.agent_v2.ask_human_resume import AskHumanResumeOutcome
from core.workflow.nodes.agent_v2.dify_tools_builder import WorkflowAgentToolLayers
from graphon.model_runtime.entities.llm_entities import LLMResult, LLMUsage
from graphon.model_runtime.errors.invoke import InvokeRateLimitError
@@ -306,7 +302,7 @@ class _StreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):
created_at=created_at,
data=RunSucceededEventData(
output={"text": "hello agent"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
usage=AgentRunUsage(
prompt_tokens=3,
prompt_unit_price=Decimal(5),
@@ -382,7 +378,7 @@ class _StreamingSingleAgentMessageDeltaFakeAgentBackendRunClient(FakeAgentBacken
created_at=created_at,
data=RunSucceededEventData(
output={"text": "hello agent"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
@@ -405,7 +401,7 @@ class _NullOutputFakeAgentBackendRunClient(FakeAgentBackendRunClient):
created_at=created_at,
data=RunSucceededEventData(
output=None,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
@@ -435,7 +431,7 @@ class _StreamingTextNullOutputFakeAgentBackendRunClient(FakeAgentBackendRunClien
created_at=created_at,
data=RunSucceededEventData(
output=None,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
@@ -472,7 +468,7 @@ class _AgentAnswerStreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):
created_at=created_at,
data=RunSucceededEventData(
output={"text": "final answer"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
@@ -520,7 +516,7 @@ class _ProcessStreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):
created_at=created_at,
data=RunSucceededEventData(
output={"text": "final answer"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
@@ -528,7 +524,7 @@ class _ProcessStreamingFakeAgentBackendRunClient(FakeAgentBackendRunClient):
class _FakeSessionStore:
def __init__(
self,
- loaded: CompositorSessionSnapshot | None = None,
+ loaded: SessionSnapshot | None = None,
loaded_session: StoredAgentAppSession | None = None,
binding_id: str = "binding-1",
workspace_id: str = "workspace-1",
@@ -544,7 +540,7 @@ class _FakeSessionStore:
tuple[
AgentAppSessionScope,
str,
- CompositorSessionSnapshot | None,
+ SessionSnapshot | None,
str | None,
str | None,
]
@@ -567,17 +563,15 @@ class _FakeSessionStore:
*,
scope: AgentAppSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
+ snapshot: SessionSnapshot | None,
) -> None:
- self.saved.append((scope, binding_id, snapshot, pending_form_id, pending_tool_call_id))
+ self.saved.append((scope, binding_id, snapshot))
class _ExplodingSessionStore(_FakeSessionStore):
- def __init__(self, loaded: CompositorSessionSnapshot | None = None) -> None:
+ def __init__(self, loaded: SessionSnapshot | None = None) -> None:
super().__init__(loaded=loaded)
- self.save_attempts: list[CompositorSessionSnapshot | None] = []
+ self.save_attempts: list[SessionSnapshot | None] = []
@override
def save_active_snapshot(
@@ -585,11 +579,9 @@ class _ExplodingSessionStore(_FakeSessionStore):
*,
scope: AgentAppSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
+ snapshot: SessionSnapshot | None,
) -> None:
- del scope, binding_id, pending_form_id, pending_tool_call_id
+ del scope, binding_id
self.save_attempts.append(snapshot)
raise RuntimeError("session save failed")
@@ -630,7 +622,7 @@ def _dify_ctx() -> DifyRunContext:
)
-def _compatible_session_snapshot() -> CompositorSessionSnapshot:
+def _compatible_session_snapshot() -> SessionSnapshot:
request = (
AgentAppRuntimeRequestBuilder(
dify_tools_builder=_NoToolsBuilder(), # type: ignore[arg-type]
@@ -650,12 +642,7 @@ def _compatible_session_snapshot() -> CompositorSessionSnapshot:
)
.request
)
- return CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(name=layer.name, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={})
- for layer in request.composition.layers
- ]
- )
+ return SessionSnapshot(layers={layer.name: {} for layer in request.composition.layers})
def _runner(
@@ -744,7 +731,6 @@ def test_successful_turn_publishes_chunk_and_message_end_and_saves_session() ->
_run(_runner(client, store), qm)
assert client.request is not None
- assert client.request.on_exit.default.value == "suspend"
# One LLM chunk + one message-end, carrying the backend's answer text.
chunk_events = [e for e in qm.events if isinstance(e, QueueLLMChunkEvent)]
end_events = [e for e in qm.events if isinstance(e, QueueMessageEndEvent)]
@@ -756,14 +742,11 @@ def test_successful_turn_publishes_chunk_and_message_end_and_saves_session() ->
assert _saved_user_query(qm) == "hello"
# The conversation session snapshot is persisted for multi-turn continuity.
assert store.saved
- saved_scope, saved_binding_id, saved_snapshot, pending_form_id, pending_tool_call_id = store.saved[0]
+ saved_scope, saved_binding_id, saved_snapshot = store.saved[0]
assert saved_scope.conversation_id == "conv-1"
assert saved_scope.agent_config_snapshot_id == "snap-1"
assert saved_binding_id == "binding-1"
assert saved_snapshot is not None
- # A successful turn carries no ask_human pause correlation.
- assert pending_form_id is None
- assert pending_tool_call_id is None
def test_turn_uses_resolved_backend_binding_before_backend_invocation() -> None:
@@ -1355,19 +1338,17 @@ def test_prior_session_snapshot_is_threaded_into_request() -> None:
assert client.request.session_snapshot is prior
-def test_incompatible_session_snapshot_is_rejected_before_backend_invocation() -> None:
+def test_snapshot_with_removed_optional_prompt_is_forwarded_to_runtime() -> None:
compatible = _compatible_session_snapshot()
- stale = CompositorSessionSnapshot(
- layers=[layer for layer in compatible.layers if layer.name != "agent_soul_prompt"]
+ snapshot = SessionSnapshot(
+ layers={name: state for name, state in compatible.layers.items() if name != "agent_soul_prompt"}
)
client = FakeAgentBackendRunClient()
- store = _FakeSessionStore(loaded=stale)
-
- with pytest.raises(AgentSessionSnapshotIncompatibleError, match="Start a new conversation"):
- _run(_runner(client, store), _FakeQueueManager())
-
- assert client.request is None
- assert store.saved == []
+ store = _FakeSessionStore(loaded=snapshot)
+ _run(_runner(client, store), _FakeQueueManager())
+ assert client.request is not None
+ assert client.request.session_snapshot is snapshot
+ assert len(store.saved) == 1
def test_debug_session_scope_can_reuse_conversation_across_config_snapshots() -> None:
@@ -1405,7 +1386,7 @@ def test_failed_run_raises_agent_backend_error() -> None:
_run(_runner(client, store), qm)
# No message-end on failure; post-exit session state is still saved.
assert not [e for e in qm.events if isinstance(e, QueueMessageEndEvent)]
- assert store.saved[0][2] == CompositorSessionSnapshot(layers=[])
+ assert store.saved[0][2] == SessionSnapshot(layers={})
def test_failed_run_persists_partial_usage(sqlite_session: Session) -> None:
@@ -1477,7 +1458,7 @@ def test_snapshot_save_failure_preserves_original_app_outcome(outcome: str) -> N
with pytest.raises(expected_error, match="fake failure" if outcome == "failed" else None):
_run(_runner(client, store), queue_manager)
- assert store.save_attempts == [CompositorSessionSnapshot(layers=[])]
+ assert store.save_attempts == [SessionSnapshot(layers={})]
@pytest.mark.parametrize(
@@ -1573,7 +1554,7 @@ def test_stopped_task_waits_for_cancelled_snapshot_and_saves_session() -> None:
assert client.cancelled_run_ids == ["fake-run-1"]
assert len(store.saved) == 1
- assert store.saved[0][2] == CompositorSessionSnapshot(layers=[])
+ assert store.saved[0][2] == SessionSnapshot(layers={})
def test_stopped_task_persists_partial_usage(sqlite_session: Session) -> None:
@@ -1610,73 +1591,3 @@ def test_terminal_output_to_answer_handles_plain_string_and_dict() -> None:
assert AgentAppRunner._terminal_output_to_answer("plain text") == "plain text"
assert AgentAppRunner._terminal_output_to_answer({"text": "hi"}) == "hi"
assert AgentAppRunner._terminal_output_to_answer({"a": 1}) == '{"a": 1}'
-
-
-def test_ask_human_pauses_turn_creates_form_and_persists_correlation() -> None:
- # ENG-635/637: the PAUSED scenario emits a dify.ask_human deferred call, so
- # the chat turn ends by creating a conversation-owned HITL form + saving the
- # pause correlation, instead of crashing. Stub the form repo (DB-free).
- client = _UsagePausedClient()
- store = _FakeSessionStore()
- qm = _FakeQueueManager()
- runner = _runner(client, store)
-
- fake_repo = MagicMock()
- fake_repo.create_form.return_value = MagicMock(id="form-1")
- runner._build_form_repository = lambda dify_context: fake_repo # type: ignore[assignment]
-
- _run(runner, qm)
-
- # The conversation-owned form was created and the agent's question surfaced.
- fake_repo.create_form.assert_called_once()
- created_params = fake_repo.create_form.call_args.args[0]
- assert created_params.conversation_id == "conv-1"
- assert created_params.workflow_execution_id is None
- assert [e for e in qm.events if isinstance(e, QueueMessageEndEvent)]
- assert _saved_user_query(qm) == "hello"
- assert _llm_result(qm).usage.total_tokens == 8
- # The pause correlation is persisted so a form submission can resume the run.
- assert store.saved
- assert store.saved[0][3] == "form-1"
- assert store.saved[0][4] == "fake-ask-human-1"
-
-
-def test_submitted_form_resumes_turn_with_deferred_tool_results(monkeypatch: pytest.MonkeyPatch) -> None:
- # ENG-638: a turn that runs while a pending form is answered threads the
- # human's reply into the request as deferred_tool_results.
- snapshot = _compatible_session_snapshot()
- stored = StoredAgentAppSession(
- scope=AgentAppSessionScope(
- tenant_id="tenant-1",
- app_id="app-1",
- conversation_id="conv-1",
- agent_id="agent-1",
- agent_config_snapshot_id="snap-1",
- home_snapshot_id="home-1",
- ),
- binding_id="binding-1",
- workspace_id="workspace-1",
- backend_binding_ref="backend-binding-1",
- session_snapshot=snapshot,
- pending_form_id="form-1",
- pending_tool_call_id="call-1",
- )
- store = _FakeSessionStore(loaded_session=stored)
- submitted = AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status="submitted", values={"ok": True}))
- monkeypatch.setattr(
- "core.app.apps.agent_app.app_runner.resolve_ask_human_form",
- lambda **_kwargs: submitted,
- )
-
- client = FakeAgentBackendRunClient() # SUCCESS -> the resumed run completes
- qm = _FakeQueueManager()
- _run(_runner(client, store), qm)
-
- assert client.request is not None
- assert client.request.deferred_tool_results is not None
- assert set(client.request.deferred_tool_results.calls) == {"call-1"}
- # ENG-638: the resume composition must keep the user-prompt layer so it
- # matches the suspended snapshot's layer names (the agent backend rejects a
- # mismatch). A resume therefore re-sends a non-blank query, never blank.
- layer_names = [layer.name for layer in client.request.composition.layers]
- assert "agent_app_user_prompt" in layer_names
diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py b/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
index b93f0e6ff90..f7a122427f4 100644
--- a/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_runtime_request_builder.py
@@ -6,13 +6,14 @@ from __future__ import annotations
from types import SimpleNamespace
import pytest
-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot
-from agenton.layers import LifecycleState
-from dify_agent.layers.config import DifyConfigSkillConfig
+from dify_agent.layers.config import DifyConfigLayerConfig, DifyConfigSkillConfig
from dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfig
-from dify_agent.layers.dify_plugin import DifyPluginToolConfig, DifyPluginToolsLayerConfig
+from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig, DifyPluginToolConfig, DifyPluginToolsLayerConfig
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
+from dify_agent.layers.knowledge import DifyKnowledgeBaseLayerConfig
+from dify_agent.layers.prompt import Config as PromptConfig
from dify_agent.layers.user_prompt import DifyUserPromptLayerConfig
+from dify_agent.protocol.snapshot import SessionSnapshot
from clients.agent_backend import (
DIFY_CONFIG_LAYER_ID,
@@ -23,7 +24,6 @@ from clients.agent_backend import (
AgentBackendRunRequestBuilder,
)
from clients.agent_backend.request_builder import DIFY_SHELL_LAYER_ID
-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleError
from core.app.apps.agent_app.runtime_request_builder import (
AgentAppRuntimeBuildContext,
AgentAppRuntimeRequestBuilder,
@@ -90,7 +90,6 @@ class TestBuildForAgentApp:
]
assert "workflow_node_job_prompt" not in names
# Agent App keeps layers alive across turns by default.
- assert request.on_exit.default.value == "suspend"
def test_blank_user_prompt_rejected(self):
with pytest.raises(ValueError, match="must not be blank"):
@@ -171,7 +170,7 @@ def _ctx(
*,
query: str = "hello",
agent_config_version_kind: str = "snapshot",
- session_snapshot: CompositorSessionSnapshot | None = None,
+ session_snapshot: SessionSnapshot | None = None,
files: tuple[File, ...] = (),
image_detail_config: ImagePromptMessageContent.DETAIL | None = None,
) -> AgentAppRuntimeBuildContext:
@@ -238,13 +237,8 @@ def _document_file() -> File:
)
-def _snapshot_for_layer_names(layer_names: list[str]) -> CompositorSessionSnapshot:
- return CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(name=name, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={})
- for name in layer_names
- ]
- )
+def _snapshot_for_layer_names(layer_names: list[str]) -> SessionSnapshot:
+ return SessionSnapshot(layers={name: {} for name in layer_names})
class TestAgentAppRuntimeRequestBuilder:
@@ -269,18 +263,17 @@ class TestAgentAppRuntimeRequestBuilder:
]
# plugin_id / provider normalized for plugin-daemon transport.
llm = next(layer for layer in req.composition.layers if layer.name == "llm")
- assert llm.config.plugin_id == "langgenius/openai"
- assert llm.config.model_provider == "openai"
- assert llm.config.context_window_tokens == 32_768
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).plugin_id == "langgenius/openai"
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).model_provider == "openai"
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).context_window_tokens == 32_768
assert model_context_window_calls == [(context.dify_context, "langgenius/openai/openai", "gpt-4o-mini")]
# execution context carries conversation + agent_app invoke source.
exec_ctx = next(layer for layer in req.composition.layers if layer.name == "execution_context")
- assert exec_ctx.config.conversation_id == "conv-1"
+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).conversation_id == "conv-1"
# Real Dify access context forwarded; agent run mode in agent_mode.
- assert exec_ctx.config.user_from == "end-user"
- assert exec_ctx.config.invoke_from == "web-app"
- assert exec_ctx.config.agent_mode == "agent_app"
- assert req.on_exit.default.value == "suspend"
+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).user_from == "end-user"
+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).invoke_from == "web-app"
+ assert DifyExecutionContextLayerConfig.model_validate(exec_ctx.config).agent_mode == "agent_app"
# LLM credentials are resolved by API and never enter the Agent request.
assert "credentials" not in result.redacted_request["composition"]["layers"][-1]["config"]
assert result.metadata["conversation_id"] == "conv-1"
@@ -418,7 +411,7 @@ class TestAgentAppRuntimeRequestBuilder:
("previous_prompt", "current_prompt"),
[("", "You are Iris."), ("You are Iris.", "")],
)
- def test_build_rejects_session_snapshot_after_layer_topology_changes(
+ def test_build_preserves_snapshot_when_optional_prompt_modules_change(
self,
previous_prompt: str,
current_prompt: str,
@@ -433,18 +426,9 @@ class TestAgentAppRuntimeRequestBuilder:
current_soul = _soul_with_model()
current_soul.prompt.system_prompt = current_prompt
- with pytest.raises(AgentSessionSnapshotIncompatibleError) as exc_info:
- builder.build(
- _ctx(
- current_soul,
- agent_config_version_kind="draft",
- session_snapshot=snapshot,
- )
- )
-
- assert exc_info.value.error_code == "agent_session_configuration_changed"
- assert exc_info.value.status_code == 409
- assert "Start a new conversation" in str(exc_info.value)
+ result = builder.build(_ctx(current_soul, agent_config_version_kind="draft", session_snapshot=snapshot))
+ assert result.request.session_snapshot is snapshot
+ assert ("agent_soul_prompt" in {s.name for s in result.request.composition.layers}) == bool(current_prompt)
def test_build_reuses_session_snapshot_when_config_changes_without_changing_layers(self) -> None:
builder = AgentAppRuntimeRequestBuilder(
@@ -473,9 +457,9 @@ class TestAgentAppRuntimeRequestBuilder:
result = builder.build(_ctx(_soul_with_model(), agent_config_version_kind="build_draft"))
prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert prompt_layer.config.prefix != _soul_with_model().prompt
- assert prompt_layer.config.prefix.startswith("You are running in build mode.")
- assert "```text\nYou are Iris.\n```" in prompt_layer.config.prefix
+ assert PromptConfig.model_validate(prompt_layer.config).prefix != _soul_with_model().prompt
+ assert PromptConfig.model_validate(prompt_layer.config).prefix.startswith("You are running in build mode.")
+ assert "```text\nYou are Iris.\n```" in PromptConfig.model_validate(prompt_layer.config).prefix
def test_build_propagates_draft_version_kind_without_wrapping_prompt(self):
builder = AgentAppRuntimeRequestBuilder(
@@ -490,9 +474,12 @@ class TestAgentAppRuntimeRequestBuilder:
)
config_layer = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)
- assert prompt_layer.config.prefix == "You are Iris."
- assert execution_context.config.agent_config_version_kind == "draft"
- assert config_layer.config.config_version.kind == "draft"
+ assert PromptConfig.model_validate(prompt_layer.config).prefix == "You are Iris."
+ assert (
+ DifyExecutionContextLayerConfig.model_validate(execution_context.config).agent_config_version_kind
+ == "draft"
+ )
+ assert DifyConfigLayerConfig.model_validate(config_layer.config).config_version.kind == "draft"
def test_build_includes_plugin_tools_layer_returned_by_injected_builder_for_draft(self):
soul = _soul_with_model()
@@ -565,8 +552,8 @@ class TestAgentAppRuntimeRequestBuilder:
result = builder.build(_ctx(soul))
llm = next(layer for layer in result.request.composition.layers if layer.name == "llm")
- assert llm.config.plugin_id == "langgenius/openai"
- assert llm.config.model_provider == "openai"
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).plugin_id == "langgenius/openai"
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).model_provider == "openai"
def test_build_normalizes_legacy_three_segment_model_plugin_id(self):
soul = _soul_with_model()
@@ -578,8 +565,8 @@ class TestAgentAppRuntimeRequestBuilder:
result = builder.build(_ctx(soul))
llm = next(layer for layer in result.request.composition.layers if layer.name == "llm")
- assert llm.config.plugin_id == "langgenius/openai"
- assert llm.config.model_provider == "openai"
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).plugin_id == "langgenius/openai"
+ assert DifyPluginLLMLayerConfig.model_validate(llm.config).model_provider == "openai"
def test_build_maps_agent_soul_knowledge_to_knowledge_layer(self):
soul = AgentSoulConfig.model_validate(
@@ -613,9 +600,10 @@ class TestAgentAppRuntimeRequestBuilder:
result = builder.build(_ctx(soul))
knowledge = next(layer for layer in result.request.composition.layers if layer.name == "knowledge")
- assert knowledge.type == "dify.knowledge_base"
- assert knowledge.deps == {"execution_context": "execution_context"}
- dumped_config = knowledge.config.model_dump(mode="json", by_alias=True)
+ assert knowledge.config["execution_context"] == "execution_context"
+ dumped_config = DifyKnowledgeBaseLayerConfig.model_validate(knowledge.config).model_dump(
+ mode="json", by_alias=True
+ )
knowledge_set = dumped_config["sets"][0]
assert [dataset["id"] for dataset in knowledge_set["datasets"]] == ["dataset-1", "dataset-2"]
assert knowledge_set["query"] == {"mode": "generated_query", "value": None}
@@ -693,18 +681,21 @@ class TestAgentAppConfigLayer:
result = builder.build(_ctx(_soul_with_model_and_skill()))
config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)
- assert config.type == "dify.config"
- assert config.deps == {"shell": DIFY_SHELL_LAYER_ID}
- assert config.config.agent_id == "agent-1"
- assert config.config.config_version is not None
- assert config.config.config_version.id == "snap-1"
- assert config.config.config_version.kind == "snapshot"
- assert config.config.config_version.writable is False
- assert [skill.name for skill in config.config.skills] == ["tender-analyzer"]
- assert [file_ref.name for file_ref in config.config.files] == ["sample.pdf"]
- assert config.config.note == "Read the proposal first."
- assert config.config.mentioned_skill_names == ["tender-analyzer"]
- assert config.config.mentioned_file_names == []
+ assert config.config["shell"] == DIFY_SHELL_LAYER_ID
+ assert DifyConfigLayerConfig.model_validate(config.config).agent_id == "agent-1"
+ assert DifyConfigLayerConfig.model_validate(config.config).config_version is not None
+ assert DifyConfigLayerConfig.model_validate(config.config).config_version.id == "snap-1"
+ assert DifyConfigLayerConfig.model_validate(config.config).config_version.kind == "snapshot"
+ assert DifyConfigLayerConfig.model_validate(config.config).config_version.writable is False
+ assert [skill.name for skill in DifyConfigLayerConfig.model_validate(config.config).skills] == [
+ "tender-analyzer"
+ ]
+ assert [file_ref.name for file_ref in DifyConfigLayerConfig.model_validate(config.config).files] == [
+ "sample.pdf"
+ ]
+ assert DifyConfigLayerConfig.model_validate(config.config).note == "Read the proposal first."
+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_skill_names == ["tender-analyzer"]
+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_file_names == []
# shell enters first; config uses that shell to materialize mentioned targets.
names = [layer.name for layer in result.request.composition.layers]
assert names.index(DIFY_SHELL_LAYER_ID) == names.index("execution_context") + 2
@@ -719,7 +710,8 @@ class TestAgentAppConfigLayer:
result = builder.build(_ctx(_soul_with_model()))
layers = {layer.name: layer for layer in result.request.composition.layers}
- assert layers[DIFY_CONFIG_LAYER_ID].config.model_dump(mode="json") == {
+ assert DifyConfigLayerConfig.model_validate(layers[DIFY_CONFIG_LAYER_ID].config).model_dump(mode="json") == {
+ "shell": "shell",
"agent_id": "agent-1",
"config_version": {"id": "snap-1", "kind": "snapshot", "writable": False},
"skills": [],
@@ -729,10 +721,8 @@ class TestAgentAppConfigLayer:
"mentioned_skill_names": [],
"mentioned_file_names": [],
}
- assert layers[DIFY_SHELL_LAYER_ID].deps == {
- "execution_context": "execution_context",
- "runtime": "runtime",
- }
+ assert layers[DIFY_SHELL_LAYER_ID].config["execution_context"] == "execution_context"
+ assert layers[DIFY_SHELL_LAYER_ID].config["runtime"] == "runtime"
def test_config_layer_for_build_draft_marks_config_writable(self):
builder = AgentAppRuntimeRequestBuilder(
@@ -742,7 +732,8 @@ class TestAgentAppConfigLayer:
result = builder.build(_ctx(_soul_with_model_and_skill(), agent_config_version_kind="build_draft"))
config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)
- assert config.config.model_dump(mode="json") == {
+ assert DifyConfigLayerConfig.model_validate(config.config).model_dump(mode="json") == {
+ "shell": "shell",
"agent_id": "agent-1",
"config_version": {"id": "snap-1", "kind": "build_draft", "writable": True},
"skills": [
@@ -781,10 +772,12 @@ class TestAgentAppConfigLayer:
result = builder.build(_ctx(soul))
config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)
- assert [skill.name for skill in config.config.skills] == ["workspace-skill"]
- assert config.config.mentioned_skill_names == ["workspace-skill"]
+ assert [skill.name for skill in DifyConfigLayerConfig.model_validate(config.config).skills] == [
+ "workspace-skill"
+ ]
+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_skill_names == ["workspace-skill"]
prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert prompt_layer.config.prefix == "Use workspace-skill."
+ assert PromptConfig.model_validate(prompt_layer.config).prefix == "Use workspace-skill."
@pytest.mark.parametrize(
("system_prompt", "expected_prefix"),
@@ -813,8 +806,8 @@ class TestAgentAppConfigLayer:
result = builder.build(_ctx(soul))
prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert prompt_layer.config.prefix == expected_prefix
- assert "[§" not in prompt_layer.config.prefix
+ assert PromptConfig.model_validate(prompt_layer.config).prefix == expected_prefix
+ assert "[§" not in PromptConfig.model_validate(prompt_layer.config).prefix
def test_agent_app_runtime_missing_config_mentions_fall_back_without_marker_leak(
self,
@@ -830,8 +823,10 @@ class TestAgentAppConfigLayer:
result = builder.build(_ctx(soul))
prompt_layer = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert prompt_layer.config.prefix == "Use Ghost Skill, Ghost File, and no-label.txt."
- assert "[§" not in prompt_layer.config.prefix
+ assert (
+ PromptConfig.model_validate(prompt_layer.config).prefix == "Use Ghost Skill, Ghost File, and no-label.txt."
+ )
+ assert "[§" not in PromptConfig.model_validate(prompt_layer.config).prefix
assert [warning["code"] for warning in result.metadata["runtime_support"]["unsupported_runtime_warnings"]] == [
"mention_target_missing",
"mention_target_missing",
diff --git a/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py b/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py
index 54850885428..936d2fc79df 100644
--- a/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py
+++ b/api/tests/unit_tests/core/app/apps/agent_app/test_session_store.py
@@ -1,7 +1,7 @@
from unittest.mock import MagicMock
import pytest
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from sqlalchemy.orm import Session, sessionmaker
from core.app.apps.agent_app.session_store import AgentAppSessionScope, AgentAppWorkspaceStore
@@ -167,7 +167,7 @@ def test_normal_conversation_pointer_does_not_create_replacement_binding(
def test_save_snapshot_targets_binding(monkeypatch: pytest.MonkeyPatch) -> None:
save = MagicMock()
monkeypatch.setattr(AgentWorkspaceService, "save_binding_session_snapshot", save)
- snapshot = CompositorSessionSnapshot(layers=[])
+ snapshot = SessionSnapshot(layers={})
AgentAppWorkspaceStore().save_active_snapshot(scope=_scope(), binding_id="binding-1", snapshot=snapshot)
diff --git a/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py b/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py
index 26b3f521a3e..18c2fdd97a2 100644
--- a/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py
+++ b/api/tests/unit_tests/core/app/task_pipeline/test_based_generate_task_pipeline.py
@@ -7,7 +7,6 @@ from dify_agent.protocol import RunFailureType
from sqlalchemy.orm import Session
from clients.agent_backend.errors import AgentBackendRunFailedError
-from core.app.apps.agent_app.errors import AgentSessionSnapshotIncompatibleError
from core.app.apps.base_app_generate_response_converter import AppGenerateResponseConverter
from core.app.entities.app_invoke_entities import InvokeFrom
from core.app.entities.queue_entities import QueueErrorEvent
@@ -169,17 +168,6 @@ class TestBasedGenerateTaskPipeline:
"message": "run limit reached (agent_run_id=run-1)",
}
- def test_stream_converter_preserves_agent_session_configuration_error(self):
- data = AppGenerateResponseConverter._error_to_stream_response(AgentSessionSnapshotIncompatibleError())
-
- assert data == {
- "code": "agent_session_configuration_changed",
- "status": 409,
- "message": (
- "The Agent configuration changed after this conversation started. Start a new conversation to continue."
- ),
- }
-
def test_handle_output_moderation_when_flagged(self, pipeline):
handler = Mock()
handler.moderation_completion.return_value = ("filtered", True)
diff --git a/api/tests/unit_tests/core/repositories/test_human_input_repository.py b/api/tests/unit_tests/core/repositories/test_human_input_repository.py
index 6e149fdb697..6aaa0596152 100644
--- a/api/tests/unit_tests/core/repositories/test_human_input_repository.py
+++ b/api/tests/unit_tests/core/repositories/test_human_input_repository.py
@@ -425,6 +425,28 @@ def test_create_form_adds_console_and_backstage_recipients(
}
+def test_create_runtime_form_requires_workflow_even_when_conversation_is_present() -> None:
+ repo = HumanInputFormRepositoryImpl(tenant_id="tenant", app_id="app")
+ params = FormCreateParams(
+ workflow_execution_id=None,
+ conversation_id="conversation",
+ node_id="node",
+ form_config=HumanInputNodeData(
+ title="Title",
+ delivery_methods=[],
+ form_content="hello",
+ inputs=[],
+ user_actions=[UserActionConfig(id="submit", title="Submit")],
+ ),
+ rendered_content="hello",
+ delivery_methods=[],
+ display_in_ui=True,
+ resolved_default_values={},
+ )
+ with pytest.raises(ValueError, match="requires a workflow_execution_id"):
+ repo.create_form(params)
+
+
def test_submission_get_by_token_returns_none_when_missing_or_form_missing(repository_session: Session) -> None:
repo = HumanInputFormSubmissionRepository()
assert repo.get_by_token("tok") is None
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py
index f4632563260..ddf64c31d6b 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_agent_node.py
@@ -6,8 +6,6 @@ from unittest.mock import MagicMock, patch
from uuid import UUID, uuid4
import pytest
-from agenton.compositor import CompositorSessionSnapshot
-from dify_agent.layers.ask_human import AskHumanToolResult
from dify_agent.protocol import (
DIFY_AGENT_OUTPUT_LAYER_ID,
CancelRunRequest,
@@ -22,6 +20,7 @@ from dify_agent.protocol import (
RunSucceededEvent,
RunSucceededEventData,
)
+from dify_agent.protocol.snapshot import SessionSnapshot
from pydantic_ai.messages import PartDeltaEvent, TextPartDelta
from clients.agent_backend import (
@@ -36,7 +35,6 @@ from clients.agent_backend import (
from core.app.entities.app_invoke_entities import DIFY_RUN_CONTEXT_KEY, DifyRunContext, InvokeFrom, UserFrom
from core.workflow.file_reference import build_file_reference
from core.workflow.nodes.agent_v2 import DifyAgentNode
-from core.workflow.nodes.agent_v2.ask_human_resume import AskHumanResumeOutcome
from core.workflow.nodes.agent_v2.binding_resolver import WorkflowAgentBindingBundle, WorkflowAgentBindingResolver
from core.workflow.nodes.agent_v2.entities import DifyAgentNodeData
from core.workflow.nodes.agent_v2.output_adapter import WorkflowAgentOutputAdapter
@@ -49,9 +47,7 @@ from core.workflow.nodes.agent_v2.session_store import (
WorkflowAgentSessionScope,
WorkflowAgentWorkspaceStore,
)
-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired
from graphon.entities import GraphInitParams
-from graphon.entities.pause_reason import HitlRequired
from graphon.enums import (
BuiltinNodeTypes,
ErrorStrategy,
@@ -60,7 +56,6 @@ from graphon.enums import (
WorkflowNodeExecutionStatus,
)
from graphon.file import File, FileTransferMethod, FileType
-from graphon.graph_events import NodeRunPauseRequestedEvent
from graphon.node_events import StreamCompletedEvent
from graphon.runtime import GraphRuntimeState
from graphon.variables.segments import ArrayFileSegment, FileSegment, StringSegment
@@ -159,7 +154,7 @@ class FakeBindingResolver(WorkflowAgentBindingResolver):
class FakeSessionStore:
def __init__(
self,
- snapshot: CompositorSessionSnapshot | None = None,
+ snapshot: SessionSnapshot | None = None,
*,
binding_id: str = "binding-1",
workspace_id: str = "workspace-1",
@@ -177,7 +172,7 @@ class FakeSessionStore:
tuple[
WorkflowAgentSessionScope,
str,
- CompositorSessionSnapshot | None,
+ SessionSnapshot | None,
str | None,
str | None,
]
@@ -210,28 +205,24 @@ class FakeSessionStore:
*,
scope: WorkflowAgentSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
+ snapshot: SessionSnapshot | None,
) -> None:
- self.saved.append((scope, binding_id, snapshot, pending_form_id, pending_tool_call_id))
+ self.saved.append((scope, binding_id, snapshot))
class ExplodingSessionStore(FakeSessionStore):
- def __init__(self, snapshot: CompositorSessionSnapshot | None = None) -> None:
+ def __init__(self, snapshot: SessionSnapshot | None = None) -> None:
super().__init__(snapshot=snapshot)
- self.save_attempts: list[CompositorSessionSnapshot | None] = []
+ self.save_attempts: list[SessionSnapshot | None] = []
def save_active_snapshot(
self,
*,
scope: WorkflowAgentSessionScope,
binding_id: str,
- snapshot: CompositorSessionSnapshot | None,
- pending_form_id: str | None = None,
- pending_tool_call_id: str | None = None,
+ snapshot: SessionSnapshot | None,
) -> None:
- del scope, binding_id, pending_form_id, pending_tool_call_id
+ del scope, binding_id
self.save_attempts.append(snapshot)
raise RuntimeError("simulated DB failure")
@@ -244,7 +235,7 @@ class FileOutputBackendClient(FakeAgentBackendRunClient):
self.output_payload = output_payload
def _events(self, run_id: str):
- from agenton.compositor import CompositorSessionSnapshot
+ from dify_agent.protocol.snapshot import SessionSnapshot
from clients.agent_backend.fake_client import _FIXED_TIME
@@ -256,7 +247,7 @@ class FileOutputBackendClient(FakeAgentBackendRunClient):
created_at=_FIXED_TIME,
data=RunSucceededEventData(
output=self.output_payload,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
),
)
@@ -274,7 +265,7 @@ class PlainTextOutputBackendClient(FakeAgentBackendRunClient):
created_at=_FIXED_TIME,
data=RunSucceededEventData(
output="hello agent",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
),
)
@@ -298,7 +289,7 @@ class AgentMessageDeltaBackendClient(FakeAgentBackendRunClient):
created_at=created_at,
data=RunSucceededEventData(
output={"text": "hello agent"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
),
)
@@ -758,11 +749,11 @@ def test_agent_node_run_maps_failed_agent_backend_run_to_node_result():
assert result.status == WorkflowNodeExecutionStatus.FAILED
assert result.error == "fake failure"
assert result.error_type == "unit_test"
- assert store.saved[0][2] == CompositorSessionSnapshot(layers=[])
+ assert store.saved[0][2] == SessionSnapshot(layers={})
def test_agent_node_saves_success_snapshot_and_reuses_existing_snapshot():
- existing_snapshot = CompositorSessionSnapshot(layers=[])
+ existing_snapshot = SessionSnapshot(layers={})
store = FakeSessionStore(snapshot=existing_snapshot)
client = FakeAgentBackendRunClient()
node = _node(agent_backend_client=client, session_store=store)
@@ -771,13 +762,10 @@ def test_agent_node_saves_success_snapshot_and_reuses_existing_snapshot():
assert len(events) == 1
assert store.saved
- scope, binding_id, saved_snapshot, pending_form_id, pending_tool_call_id = store.saved[0]
+ scope, binding_id, saved_snapshot = store.saved[0]
assert scope.workflow_run_id == "workflow-run-1"
assert binding_id == "binding-1"
assert saved_snapshot is not None
- # A successful terminal carries no ask_human pause correlation.
- assert pending_form_id is None
- assert pending_tool_call_id is None
assert client.request is not None
assert client.request.session_snapshot is existing_snapshot
@@ -819,7 +807,7 @@ def test_agent_node_snapshot_save_failure_preserves_original_failure(failure_kin
agent_backend = result.metadata[WorkflowNodeExecutionMetadataKey.AGENT_LOG]["agent_backend"]
assert agent_backend["session_snapshot_persisted"] is False
assert agent_backend["session_snapshot_persist_error"] == "workflow_agent_workspace_store_error"
- assert store.save_attempts == [CompositorSessionSnapshot(layers=[])]
+ assert store.save_attempts == [SessionSnapshot(layers={})]
@pytest.mark.parametrize("terminal_type", ["failed", "cancelled"])
@@ -838,137 +826,6 @@ def test_agent_node_terminal_without_snapshot_preserves_prior_session_without_wr
assert store.saved == []
-def test_agent_node_paused_run_requests_workflow_pause_and_persists_snapshot():
- store = FakeSessionStore()
- node = _node(scenario=FakeAgentBackendScenario.PAUSED, session_store=store)
-
- # ENG-636: the PAUSED scenario emits a dify.ask_human deferred call, so the
- # node now builds a HITL form and pauses with HitlRequired. Stub the
- # form repository so the unit test stays DB-free.
- fake_repo = MagicMock()
- fake_repo.create_form.return_value = MagicMock(id="form-1")
- node._build_human_input_form_repository = lambda *, dify_ctx, workflow_run_id: fake_repo # type: ignore[assignment]
-
- events = list(node._run())
-
- assert len(events) == 1
- assert isinstance(events[0], NodeRunPauseRequestedEvent)
- assert isinstance(events[0].reason, HitlRequired)
- assert events[0].reason.session_id == "form-1"
- assert events[0].reason.node_id == "agent-node"
- assert events[0].node_run_result.process_data == {
- "agent_id": "agent-1",
- "agent_config_snapshot_id": "snapshot-1",
- "workflow_agent_binding_id": "binding-1",
- }
- fake_repo.create_form.assert_called_once()
- assert store.saved
- assert store.saved[0][1] == "binding-1"
- # ENG-637: the awaiting form + deferred tool_call correlation is persisted.
- assert store.saved[0][3] == "form-1"
- assert store.saved[0][4] == "fake-ask-human-1"
-
-
-def _pending_session(snapshot: CompositorSessionSnapshot) -> StoredWorkflowAgentSession:
- return StoredWorkflowAgentSession(
- scope=WorkflowAgentSessionScope(
- tenant_id="tenant-1",
- app_id="app-1",
- workflow_id="workflow-1",
- workflow_run_id="workflow-run-1",
- node_id="agent-node",
- node_execution_id="exec-1",
- workflow_agent_binding_id="binding-1",
- agent_id="agent-1",
- agent_config_snapshot_id="snapshot-1",
- ),
- binding_id="binding-1",
- workspace_id="workspace-1",
- backend_binding_ref="backend-binding-1",
- session_snapshot=snapshot,
- pending_form_id="form-1",
- pending_tool_call_id="call-1",
- )
-
-
-def test_agent_node_resumes_with_deferred_tool_results_after_submitted_form(monkeypatch: pytest.MonkeyPatch):
- # ENG-638: a submitted form re-enters _run; the human's answer is threaded
- # into the second Agent run as deferred_tool_results.
- snapshot = CompositorSessionSnapshot(layers=[])
- store = FakeSessionStore(snapshot=snapshot)
- store.loaded_session = _pending_session(snapshot)
-
- def _fake_resolve(*, form_id: str, tenant_id: str, node_id: str) -> AskHumanResumeOutcome:
- assert form_id == "form-1"
- return AskHumanResumeOutcome(deferred_result=AskHumanToolResult(status="submitted", values={"note": "ok"}))
-
- monkeypatch.setattr("core.workflow.nodes.agent_v2.agent_node.resolve_ask_human_form", _fake_resolve)
-
- client = FakeAgentBackendRunClient() # SUCCESS scenario -> second run completes
- node = _node(agent_backend_client=client, session_store=store)
-
- events = list(node._run())
-
- assert client.request is not None
- assert client.request.deferred_tool_results is not None
- assert set(client.request.deferred_tool_results.calls) == {"call-1"}
- assert any(isinstance(event, StreamCompletedEvent) for event in events)
-
-
-def test_agent_node_repauses_when_resumed_form_still_waiting(monkeypatch: pytest.MonkeyPatch):
- snapshot = CompositorSessionSnapshot(layers=[])
- store = FakeSessionStore(snapshot=snapshot)
- store.loaded_session = _pending_session(snapshot)
-
- repause = HumanInputRequired(
- form_id="form-1",
- form_content="Approve?",
- inputs=[],
- actions=[],
- node_id="agent-node",
- node_title="Budget review",
- )
- monkeypatch.setattr(
- "core.workflow.nodes.agent_v2.agent_node.resolve_ask_human_form",
- lambda **_kwargs: AskHumanResumeOutcome(repause=repause),
- )
-
- client = FakeAgentBackendRunClient()
- node = _node(agent_backend_client=client, session_store=store)
-
- events = list(node._run())
-
- assert len(events) == 1
- assert isinstance(events[0], NodeRunPauseRequestedEvent)
- assert isinstance(events[0].reason, HitlRequired)
- assert events[0].node_run_result.process_data["workflow_agent_binding_id"] == "binding-1"
- assert client.request is None # no second Agent run was created
-
-
-def test_agent_node_expired_ask_human_failure_keeps_binding_identity(monkeypatch: pytest.MonkeyPatch):
- snapshot = CompositorSessionSnapshot(layers=[])
- store = FakeSessionStore(snapshot=snapshot)
- store.loaded_session = _pending_session(snapshot)
-
- def _raise_expired_form(**_kwargs):
- raise AssertionError("cannot resume globally expired ask_human form, form_id=form-1")
-
- monkeypatch.setattr(
- "core.workflow.nodes.agent_v2.agent_node.resolve_ask_human_form",
- _raise_expired_form,
- )
-
- events = list(_node(session_store=store)._run())
-
- assert len(events) == 1
- result = cast(StreamCompletedEvent, events[0]).node_run_result
- assert result.status == WorkflowNodeExecutionStatus.FAILED
- assert result.error == "cannot resume globally expired ask_human form, form_id=form-1"
- assert result.error_type == "agent_workflow_node_runtime_error"
- assert result.process_data["workflow_agent_binding_id"] == "binding-1"
- assert "agent_workspace_binding_id" not in result.process_data
-
-
def test_agent_node_unexpected_post_resolution_failure_keeps_binding_identity():
class _FailingSessionStore(FakeSessionStore):
def load_or_create_node_execution_session(
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_hitl.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_hitl.py
deleted file mode 100644
index 52ca2d5c0ec..00000000000
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_hitl.py
+++ /dev/null
@@ -1,351 +0,0 @@
-"""Unit tests for the ask_human -> HITL form translation layer (ENG-636)."""
-
-from __future__ import annotations
-
-from typing import Any
-
-import pytest
-from dify_agent.layers.ask_human import AskHumanToolArgs
-from dify_agent.protocol import DeferredToolCallPayload
-from pytest_mock import MockerFixture
-from sqlalchemy.orm import Session, sessionmaker
-
-from core.repositories.human_input_repository import FormCreateParams, HumanInputFormRepositoryImpl
-from core.workflow.human_input_adapter import (
- EmailDeliveryMethod,
- ExternalRecipient,
- InteractiveSurfaceDeliveryMethod,
-)
-from core.workflow.nodes.agent_v2.ask_human_hitl import (
- AskHumanFormBuildError,
- ask_human_args_to_node_data,
- build_ask_human_pause_reason,
- build_delivery_methods,
- parse_ask_human_args,
-)
-from core.workflow.nodes.human_input.entities import (
- FileInputConfig,
- FileListInputConfig,
- ParagraphInputConfig,
- SelectInputConfig,
-)
-from core.workflow.nodes.human_input.enums import ButtonStyle, TimeoutUnit
-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired
-from models.agent_config_entities import AgentHumanContactConfig
-
-
-def _args(**overrides: Any) -> AskHumanToolArgs:
- payload: dict[str, Any] = {"question": "Approve the budget?"}
- payload.update(overrides)
- return AskHumanToolArgs.model_validate(payload)
-
-
-def _deferred_call(args: dict[str, Any], *, tool_name: str = "ask_human") -> DeferredToolCallPayload:
- return DeferredToolCallPayload(tool_call_id="call-1", tool_name=tool_name, args=args)
-
-
-def repo(sqlite_session_factory: sessionmaker[Session], mocker: MockerFixture) -> HumanInputFormRepositoryImpl:
- mocker.patch(
- "core.repositories.human_input_repository.session_factory.create_session", side_effect=sqlite_session_factory
- )
- return HumanInputFormRepositoryImpl(tenant_id="tenant-1", app_id="app-1", workflow_execution_id="wf-1")
-
-
-# ─────────────────────────── parse_ask_human_args ───────────────────────────
-
-
-def test_parse_ask_human_args_from_mapping() -> None:
- parsed = parse_ask_human_args({"question": "Need a decision"})
- assert isinstance(parsed, AskHumanToolArgs)
- assert parsed.question == "Need a decision"
-
-
-def test_parse_ask_human_args_passthrough() -> None:
- original = _args()
- assert parse_ask_human_args(original) is original
-
-
-def test_parse_ask_human_args_invalid_payload_raises() -> None:
- with pytest.raises(AskHumanFormBuildError):
- parse_ask_human_args({"question": ""}) # blank question is rejected
-
-
-def test_parse_ask_human_args_non_mapping_raises() -> None:
- with pytest.raises(AskHumanFormBuildError):
- parse_ask_human_args("not a mapping")
-
-
-# ───────────────────────── ask_human_args_to_node_data ──────────────────────
-
-
-def test_node_data_maps_every_field_type() -> None:
- args = _args(
- fields=[
- {"type": "paragraph", "name": "reason", "label": "Reason", "default": "n/a"},
- {
- "type": "select",
- "name": "tier",
- "label": "Tier",
- "options": [{"value": "t1", "label": "Tier 1"}, {"value": "t2", "label": "Tier 2"}],
- "default": "t2",
- },
- {"type": "file", "name": "doc", "label": "Document"},
- {"type": "file-list", "name": "evidence", "label": "Evidence", "max_files": 3},
- ],
- )
-
- node_data = ask_human_args_to_node_data(args, node_title="Budget review")
-
- assert [type(i) for i in node_data.inputs] == [
- ParagraphInputConfig,
- SelectInputConfig,
- FileInputConfig,
- FileListInputConfig,
- ]
- paragraph, select, _file, file_list = node_data.inputs
- assert isinstance(paragraph, ParagraphInputConfig)
- assert isinstance(select, SelectInputConfig)
- assert isinstance(file_list, FileListInputConfig)
- assert paragraph.output_variable_name == "reason"
- assert paragraph.default is not None
- assert paragraph.default.value == "n/a"
- assert select.option_source.value == ["t1", "t2"]
- assert file_list.number_limits == 3
- assert node_data.timeout == 36
- assert node_data.timeout_unit == TimeoutUnit.HOUR
- assert node_data.title == "Budget review"
-
-
-def test_node_data_form_content_embeds_title_question_and_field_markers() -> None:
- args = _args(
- title="Decision needed",
- markdown="Some **context** here.",
- fields=[{"type": "paragraph", "name": "reason", "label": "Reason", "required": True}],
- )
-
- content = ask_human_args_to_node_data(args, node_title="t").form_content
-
- assert "## Decision needed" in content
- assert "Approve the budget?" in content
- assert "Some **context** here." in content
- # The label carries a required marker and positions the input via $output.
- assert "**Reason ***" in content
- assert "{{#$output.reason#}}" in content
-
-
-def test_node_data_maps_action_styles_and_titles() -> None:
- args = _args(
- actions=[
- {"id": "approve", "label": "Approve", "style": "primary"},
- {"id": "reject", "label": "Reject", "style": "destructive"},
- {"id": "later", "label": "Decide later"},
- ],
- )
-
- actions = ask_human_args_to_node_data(args, node_title="t").user_actions
-
- assert [(a.id, a.title, a.button_style) for a in actions] == [
- ("approve", "Approve", ButtonStyle.PRIMARY),
- ("reject", "Reject", ButtonStyle.ACCENT), # destructive -> accent
- ("later", "Decide later", ButtonStyle.DEFAULT),
- ]
-
-
-def test_node_data_synthesizes_submit_action_when_none_given() -> None:
- actions = ask_human_args_to_node_data(_args(), node_title="t").user_actions
- assert len(actions) == 1
- assert actions[0].id == "submit"
- assert actions[0].button_style == ButtonStyle.PRIMARY
-
-
-def test_node_data_clamps_overlong_action_id_deterministically() -> None:
- long_id = "approve_the_quarterly_budget_request" # > 20 chars, valid identifier
- args = _args(actions=[{"id": long_id, "label": "Approve"}])
-
- first = ask_human_args_to_node_data(args, node_title="t").user_actions[0]
- second = ask_human_args_to_node_data(args, node_title="t").user_actions[0]
-
- assert len(first.id) <= 20
- assert first.id.isidentifier()
- assert first.id == second.id # stable across builds
- assert first.title == "Approve" # label preserved verbatim
-
-
-# ───────────────────────────── build_delivery_methods ──────────────────────
-
-
-def test_delivery_always_includes_interactive_surface() -> None:
- methods = build_delivery_methods([], args=_args())
- assert len(methods) == 1
- assert isinstance(methods[0], InteractiveSurfaceDeliveryMethod)
-
-
-def test_delivery_adds_email_for_contacts_and_dedupes() -> None:
- contacts = [
- AgentHumanContactConfig(email="[email protected]"),
- AgentHumanContactConfig(email="[email protected]"), # duplicate
- AgentHumanContactConfig(email=None), # no email
- AgentHumanContactConfig(email="[email protected]"),
- ]
-
- methods = build_delivery_methods(contacts, args=_args())
-
- email_methods = [m for m in methods if isinstance(m, EmailDeliveryMethod)]
- assert len(email_methods) == 1
- recipients = email_methods[0].config.recipients.items
- assert [r.email for r in recipients if isinstance(r, ExternalRecipient)] == ["[email protected]", "[email protected]"]
-
-
-def test_delivery_high_urgency_prefixes_subject() -> None:
- methods = build_delivery_methods(
- [AgentHumanContactConfig(email="[email protected]")],
- args=_args(title="Sign off", urgency="high"),
- )
- email_method = next(m for m in methods if isinstance(m, EmailDeliveryMethod))
- assert email_method.config.subject.startswith("[Action needed] ")
-
-
-# ─────────────────────────── build_ask_human_pause_reason ───────────────────
-
-
-def test_pause_reason_none_for_non_ask_human_tool(repo: HumanInputFormRepositoryImpl) -> None:
- result = build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call({"question": "q"}, tool_name="final_output"),
- node_id="node-1",
- default_node_title="Agent",
- workflow_run_id="wf-1",
- contacts=[],
- repository=repo,
- )
- assert result is None
-
-
-def test_pause_reason_requires_workflow_run_id(repo: HumanInputFormRepositoryImpl) -> None:
- with pytest.raises(AskHumanFormBuildError):
- build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call({"question": "q"}),
- node_id="node-1",
- default_node_title="Agent",
- workflow_run_id="",
- contacts=[],
- repository=repo,
- )
-
-
-def test_pause_reason_builds_form_and_returns_dify_pause_reason(
- repo: HumanInputFormRepositoryImpl, mocker: MockerFixture
-) -> None:
- create = mocker.spy(repo, "create_form")
- contacts = [AgentHumanContactConfig(email="[email protected]")]
-
- result = build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call(
- {
- "title": "Approve?",
- "question": "Please approve",
- "fields": [{"type": "paragraph", "name": "note", "label": "Note"}],
- "actions": [{"id": "ok", "label": "OK"}],
- }
- ),
- node_id="node-1",
- default_node_title="Agent fallback",
- workflow_run_id="wf-1",
- contacts=contacts,
- repository=repo,
- )
-
- assert result is not None
- form = repo.get_form("node-1")
- assert form is not None
- assert result.form_id == form.id
- assert isinstance(result, HumanInputRequired)
- assert result.node_id == "node-1"
- assert result.node_title == "Approve?" # args.title wins over default
- assert [i.output_variable_name for i in result.inputs] == ["note"]
- assert [a.id for a in result.actions] == ["ok"]
-
- params: FormCreateParams = create.call_args.args[0]
- assert params.workflow_execution_id == "wf-1"
- assert params.node_id == "node-1"
- # No conversation_id passed -> pure workflow run owns the form by workflow_run_id only.
- assert params.conversation_id is None
- assert any(isinstance(m, EmailDeliveryMethod) for m in params.delivery_methods)
-
-
-def test_pause_reason_forwards_conversation_id_for_chatflow(
- repo: HumanInputFormRepositoryImpl, mocker: MockerFixture
-) -> None:
- # ENG-635 (review): an agent node running in a chatflow tags its ask_human form
- # with the conversation in addition to the workflow run.
- create = mocker.spy(repo, "create_form")
-
- build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call({"question": "Please approve"}),
- node_id="node-1",
- default_node_title="Agent",
- workflow_run_id="wf-1",
- conversation_id="conv-1",
- contacts=[],
- repository=repo,
- )
-
- params: FormCreateParams = create.call_args.args[0]
- assert params.workflow_execution_id == "wf-1"
- assert params.conversation_id == "conv-1"
-
-
-def test_pause_reason_falls_back_to_default_node_title(repo: HumanInputFormRepositoryImpl) -> None:
- result = build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call({"question": "q with no title"}),
- node_id="node-1",
- default_node_title="Agent fallback",
- workflow_run_id="wf-1",
- contacts=[],
- repository=repo,
- )
- assert result is not None
- assert result.node_title == "Agent fallback"
-
-
-def test_pause_reason_select_default_flows_into_resolved_defaults(
- repo: HumanInputFormRepositoryImpl, mocker: MockerFixture
-) -> None:
- create = mocker.spy(repo, "create_form")
- result = build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call(
- {
- "question": "pick",
- "fields": [
- {
- "type": "select",
- "name": "tier",
- "label": "Tier",
- "options": [{"value": "t1", "label": "Tier 1"}],
- "default": "t1",
- }
- ],
- }
- ),
- node_id="node-1",
- default_node_title="Agent",
- workflow_run_id="wf-1",
- contacts=[],
- repository=repo,
- )
- assert result is not None
- params: FormCreateParams = create.call_args.args[0]
- assert result.resolved_default_values == {"tier": "t1"}
-
-
-def test_pause_reason_wraps_repository_value_error(repo: HumanInputFormRepositoryImpl, mocker: MockerFixture) -> None:
- mocker.patch.object(repo, "create_form", side_effect=ValueError("db boom"))
- with pytest.raises(AskHumanFormBuildError):
- build_ask_human_pause_reason(
- deferred_tool_call=_deferred_call({"question": "q"}),
- node_id="node-1",
- default_node_title="Agent",
- workflow_run_id="wf-1",
- contacts=[],
- repository=repo,
- )
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_resume.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_resume.py
deleted file mode 100644
index 921966cc745..00000000000
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_ask_human_resume.py
+++ /dev/null
@@ -1,121 +0,0 @@
-"""Unit tests for mapping a submitted/timed-out HITL form back to ask_human (ENG-638)."""
-
-from __future__ import annotations
-
-from datetime import datetime
-
-import pytest
-from dify_agent.layers.ask_human import AskHumanToolResult
-
-from core.workflow.nodes.agent_v2.ask_human_resume import (
- build_deferred_tool_results,
- map_form_to_outcome,
-)
-from core.workflow.nodes.human_input.entities import FormDefinition, ParagraphInputConfig, UserActionConfig
-from core.workflow.nodes.human_input.enums import HumanInputFormStatus
-from core.workflow.nodes.human_input.pause_reason import HumanInputRequired
-
-
-def _form_definition_json() -> str:
- return FormDefinition(
- form_content="Approve? {{#$output.note#}}",
- inputs=[ParagraphInputConfig(output_variable_name="note")],
- user_actions=[UserActionConfig(id="approve", title="Approve"), UserActionConfig(id="reject", title="Reject")],
- rendered_content="Approve? <input>",
- expiration_time=datetime(2026, 1, 1),
- default_values={"note": "default"},
- node_title="Budget review",
- ).model_dump_json()
-
-
-def test_map_submitted_form_to_result() -> None:
- outcome = map_form_to_outcome(
- status=HumanInputFormStatus.SUBMITTED,
- selected_action_id="approve",
- submitted_data='{"note": "looks good"}',
- rendered_content="Approve? <input>",
- form_definition=_form_definition_json(),
- form_id="form-1",
- node_id="node-1",
- )
-
- assert outcome.repause is None
- result = outcome.deferred_result
- assert result is not None
- assert result.status == "submitted"
- assert result.action is not None
- assert result.action.id == "approve"
- assert result.action.label == "Approve" # verbatim label recovered from the form
- assert result.values == {"note": "looks good"}
- assert result.rendered_content == "Approve? <input>"
-
-
-def test_map_timeout_form_to_timeout_result() -> None:
- outcome = map_form_to_outcome(
- status=HumanInputFormStatus.TIMEOUT,
- selected_action_id=None,
- submitted_data=None,
- rendered_content="x",
- form_definition=_form_definition_json(),
- form_id="form-1",
- node_id="node-1",
- )
- assert outcome.deferred_result is not None
- assert outcome.deferred_result.status == "timeout"
- assert outcome.deferred_result.action is None
-
-
-def test_map_expired_form_rejects_invalid_resume_state() -> None:
- with pytest.raises(AssertionError, match="globally expired ask_human form"):
- map_form_to_outcome(
- status=HumanInputFormStatus.EXPIRED,
- selected_action_id=None,
- submitted_data=None,
- rendered_content="x",
- form_definition=_form_definition_json(),
- form_id="form-1",
- node_id="node-1",
- )
-
-
-def test_map_waiting_form_rebuilds_pause() -> None:
- outcome = map_form_to_outcome(
- status=HumanInputFormStatus.WAITING,
- selected_action_id=None,
- submitted_data=None,
- rendered_content="x",
- form_definition=_form_definition_json(),
- form_id="form-1",
- node_id="node-1",
- )
-
- assert outcome.deferred_result is None
- pause = outcome.repause
- assert isinstance(pause, HumanInputRequired)
- assert pause.form_id == "form-1"
- assert pause.node_id == "node-1"
- assert pause.node_title == "Budget review"
- assert [a.id for a in pause.actions] == ["approve", "reject"]
- assert [i.output_variable_name for i in pause.inputs] == ["note"]
-
-
-def test_map_submitted_without_action_id() -> None:
- outcome = map_form_to_outcome(
- status=HumanInputFormStatus.SUBMITTED,
- selected_action_id=None,
- submitted_data="{}",
- rendered_content="x",
- form_definition=_form_definition_json(),
- form_id="form-1",
- node_id="node-1",
- )
- assert outcome.deferred_result is not None
- assert outcome.deferred_result.action is None
- assert outcome.deferred_result.values == {}
-
-
-def test_build_deferred_tool_results_keys_by_tool_call_id() -> None:
- result = AskHumanToolResult(status="timeout")
- payload = build_deferred_tool_results(tool_call_id="call-42", result=result)
- assert set(payload.calls) == {"call-42"}
- assert payload.calls["call-42"] == result.model_dump(mode="json")
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py
index f4dd2b3b4c1..d6142285774 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_binding_resolver.py
@@ -3,7 +3,7 @@ from unittest.mock import MagicMock
from uuid import uuid4
import pytest
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from sqlalchemy import event, inspect
from sqlalchemy.orm import ORMExecuteState, Session, sessionmaker
from sqlalchemy.sql import Executable
@@ -72,7 +72,7 @@ def _conversation_participant(
base_home_snapshot_id=snapshot.home_snapshot_id,
backend_binding_ref="participant-ref",
status=AgentWorkingResourceStatus.ACTIVE,
- session_snapshot=CompositorSessionSnapshot(layers=[]).model_dump_json(),
+ session_snapshot=SessionSnapshot(layers={}).model_dump_json(),
)
session.add(participant)
session.flush()
@@ -165,7 +165,7 @@ def test_chatflow_keeps_participant_config_and_home_after_agent_update(
)
assert stored.binding_id == participant.id
assert stored.backend_binding_ref == participant.backend_binding_ref
- assert stored.session_snapshot == CompositorSessionSnapshot(layers=[])
+ assert stored.session_snapshot == SessionSnapshot(layers={})
create_binding.assert_not_called()
agent.status = AgentStatus.ARCHIVED
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py
index 9c8e5d76f74..ac635cf9afd 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_output_adapter.py
@@ -2,8 +2,8 @@ from decimal import Decimal
from unittest.mock import patch
import pytest
-from agenton.compositor import CompositorSessionSnapshot
from dify_agent.protocol import RunFailureType
+from dify_agent.protocol.snapshot import SessionSnapshot
from clients.agent_backend import (
AgentBackendRunCancelledInternalEvent,
@@ -49,7 +49,7 @@ def _succeeded(output: object) -> AgentBackendRunSucceededInternalEvent:
run_id="run-1",
source_event_id="2-0",
output=output,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
)
@@ -130,7 +130,7 @@ def test_success_output_adapter_preserves_dict_output():
run_id="run-1",
source_event_id="2-0",
output={"summary": "ok"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -152,7 +152,7 @@ def test_failure_output_adapter_preserves_backend_failed_reason():
source_event_id="2-0",
error="bad request",
reason="validation",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
usage={
"prompt_tokens": 13,
"completion_tokens": 8,
@@ -216,7 +216,7 @@ def test_success_output_adapter_normalizes_string_and_scalar_outputs():
run_id="run-1",
source_event_id="2-0",
output="hello",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -227,7 +227,7 @@ def test_success_output_adapter_normalizes_string_and_scalar_outputs():
run_id="run-2",
source_event_id="2-0",
output=3,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -264,7 +264,7 @@ def test_success_output_adapter_normalizes_file_output_to_file_segments():
}
],
},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -343,7 +343,7 @@ def test_success_output_adapter_accepts_canonical_file_mapping_for_declared_file
run_id="run-1",
source_event_id="2-0",
output={"report": {"transfer_method": "tool_file", "reference": tool_reference}},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -371,7 +371,7 @@ def test_success_output_adapter_accepts_canonical_datasource_file_mapping_for_de
run_id="run-1",
source_event_id="2-0",
output={"report": {"transfer_method": "datasource_file", "reference": datasource_reference}},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -393,7 +393,7 @@ def test_success_output_adapter_accepts_canonical_remote_url_mapping_for_declare
run_id="run-1",
source_event_id="2-0",
output={"report": {"transfer_method": "remote_url", "url": remote_url}},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -418,7 +418,7 @@ def test_success_output_adapter_accepts_canonical_file_mapping_for_declared_arra
run_id="run-1",
source_event_id="2-0",
output={"attachments": [{"transfer_method": "tool_file", "reference": tool_reference}]},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -444,7 +444,7 @@ def test_success_output_adapter_does_not_treat_generic_object_with_string_id_as_
run_id="run-1",
source_event_id="2-0",
output={"meta": {"id": "123", "type": "summary"}},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -460,7 +460,7 @@ def test_success_output_adapter_does_not_crash_on_generic_object_with_non_string
run_id="run-1",
source_event_id="2-0",
output={"meta": {"id": 1, "name": "foo"}},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -484,7 +484,7 @@ def test_success_output_adapter_preserves_nested_canonical_file_mapping_inside_o
}
}
},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -516,7 +516,7 @@ def test_success_output_adapter_preserves_nested_canonical_file_mapping_inside_g
}
]
},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
inputs={},
process_data={},
@@ -546,7 +546,7 @@ def test_success_output_adapter_maps_backend_usage_to_llm_usage_and_metadata():
run_id="run-1",
source_event_id="2-0",
output={"summary": "ok"},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
usage={
"prompt_tokens": 10,
"prompt_unit_price": "5",
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
index ffcce503042..2678610cb80 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_runtime_request_builder.py
@@ -4,11 +4,12 @@ from types import SimpleNamespace
from typing import cast
import pytest
-from agenton.compositor import CompositorSessionSnapshot
-from dify_agent.layers.config import DifyConfigSkillConfig
+from dify_agent.layers.config import DifyConfigLayerConfig, DifyConfigSkillConfig
from dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfig
from dify_agent.layers.dify_plugin import DifyPluginToolConfig, DifyPluginToolsLayerConfig
+from dify_agent.layers.prompt import Config as PromptConfig
from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID
+from dify_agent.protocol.snapshot import SessionSnapshot
from clients.agent_backend import (
DIFY_CONFIG_LAYER_ID,
@@ -709,11 +710,8 @@ def test_builds_workflow_run_request_with_dify_plugin_tools_layer(monkeypatch: p
dumped = result.request.model_dump(mode="json")
layers = {layer["name"]: layer for layer in dumped["composition"]["layers"]}
- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["type"] == "dify.plugin.tools"
- assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["deps"] == {
- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,
- "shell": DIFY_SHELL_LAYER_ID,
- }
+ assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["config"]["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["config"]["shell"] == DIFY_SHELL_LAYER_ID
assert layers[DIFY_PLUGIN_TOOLS_LAYER_ID]["config"]["tools"][0]["tool_name"] == "current_time"
assert result.metadata["agent_tools"] == {
"dify_tool_count": 1,
@@ -813,8 +811,7 @@ def test_build_maps_agent_soul_knowledge_to_knowledge_layer_config():
dumped = result.request.model_dump(mode="json")
layers = {layer["name"]: layer for layer in dumped["composition"]["layers"]}
knowledge_layer = layers["knowledge"]
- assert knowledge_layer["type"] == "dify.knowledge_base"
- assert knowledge_layer["deps"] == {"execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID}
+ assert knowledge_layer["config"]["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
assert knowledge_layer["config"]["sets"] == [
{
"id": "support",
@@ -954,7 +951,7 @@ def test_build_skips_knowledge_layer_when_agent_soul_has_no_sets():
def test_build_passes_saved_session_snapshot_to_agent_backend_request():
- session_snapshot = CompositorSessionSnapshot(layers=[])
+ session_snapshot = SessionSnapshot(layers={})
context = replace(_context(), session_snapshot=session_snapshot)
result = WorkflowAgentRuntimeRequestBuilder().build(context)
@@ -1458,6 +1455,7 @@ def test_build_config_layer_config_returns_empty_config_for_empty_agent_soul():
assert config is not None
assert config.model_dump(mode="json") == {
+ "shell": "shell",
"agent_id": None,
"config_version": {"id": None, "kind": "snapshot", "writable": False},
"skills": [],
@@ -1478,6 +1476,7 @@ def test_workflow_run_request_has_config_layer_with_empty_agent_soul(monkeypatch
dumped = result.request.model_dump(mode="json")
layers = {layer["name"]: layer for layer in dumped["composition"]["layers"]}
assert layers[DIFY_CONFIG_LAYER_ID]["config"] == {
+ "shell": "shell",
"agent_id": "agent-1",
"config_version": {"id": "snapshot-1", "kind": "snapshot", "writable": False},
"skills": [],
@@ -1487,10 +1486,8 @@ def test_workflow_run_request_has_config_layer_with_empty_agent_soul(monkeypatch
"mentioned_skill_names": [],
"mentioned_file_names": [],
}
- assert layers[DIFY_SHELL_LAYER_ID]["deps"] == {
- "execution_context": DIFY_EXECUTION_CONTEXT_LAYER_ID,
- "runtime": "runtime",
- }
+ assert layers[DIFY_SHELL_LAYER_ID]["config"]["execution_context"] == DIFY_EXECUTION_CONTEXT_LAYER_ID
+ assert layers[DIFY_SHELL_LAYER_ID]["config"]["runtime"] == "runtime"
def test_workflow_run_request_contains_config_layer():
@@ -1507,9 +1504,9 @@ def test_workflow_run_request_contains_config_layer():
assert layer_names.index(DIFY_SHELL_LAYER_ID) == layer_names.index("execution_context") + 2
assert layer_names.index(DIFY_CONFIG_LAYER_ID) == layer_names.index(DIFY_SHELL_LAYER_ID) + 1
config = next(layer for layer in dumped["composition"]["layers"] if layer["name"] == DIFY_CONFIG_LAYER_ID)
- assert config["type"] == "dify.config"
- assert config["deps"] == {"shell": DIFY_SHELL_LAYER_ID}
+ assert config["config"]["shell"] == DIFY_SHELL_LAYER_ID
assert config["config"] == {
+ "shell": "shell",
"agent_id": "agent-1",
"config_version": {"id": "snapshot-1", "kind": "snapshot", "writable": False},
"skills": [
@@ -1551,10 +1548,10 @@ def test_workflow_run_request_includes_bound_workspace_skills(monkeypatch: pytes
result = WorkflowAgentRuntimeRequestBuilder().build(context)
config = next(layer for layer in result.request.composition.layers if layer.name == DIFY_CONFIG_LAYER_ID)
- assert [skill.name for skill in config.config.skills] == ["workspace-skill"]
- assert config.config.mentioned_skill_names == ["workspace-skill"]
+ assert [skill.name for skill in DifyConfigLayerConfig.model_validate(config.config).skills] == ["workspace-skill"]
+ assert DifyConfigLayerConfig.model_validate(config.config).mentioned_skill_names == ["workspace-skill"]
soul_prompt = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert soul_prompt.config.prefix == "Use workspace-skill."
+ assert PromptConfig.model_validate(soul_prompt.config).prefix == "Use workspace-skill."
def test_workflow_runtime_expands_config_mentions_in_agent_soul_prompt():
@@ -1564,8 +1561,10 @@ def test_workflow_runtime_expands_config_mentions_in_agent_soul_prompt():
result = WorkflowAgentRuntimeRequestBuilder().build(context)
soul_prompt = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert soul_prompt.config.prefix == "You are careful. Use tender-analyzer and sample.pdf."
- assert "[§" not in soul_prompt.config.prefix
+ assert (
+ PromptConfig.model_validate(soul_prompt.config).prefix == "You are careful. Use tender-analyzer and sample.pdf."
+ )
+ assert "[§" not in PromptConfig.model_validate(soul_prompt.config).prefix
def test_workflow_runtime_missing_config_mentions_fall_back_to_label_then_name():
@@ -1582,8 +1581,8 @@ def test_workflow_runtime_missing_config_mentions_fall_back_to_label_then_name()
result = WorkflowAgentRuntimeRequestBuilder().build(context)
soul_prompt = next(layer for layer in result.request.composition.layers if layer.name == "agent_soul_prompt")
- assert soul_prompt.config.prefix == "Use Ghost Skill, Ghost File, and no-label.txt."
- assert "[§" not in soul_prompt.config.prefix
+ assert PromptConfig.model_validate(soul_prompt.config).prefix == "Use Ghost Skill, Ghost File, and no-label.txt."
+ assert "[§" not in PromptConfig.model_validate(soul_prompt.config).prefix
assert [warning["code"] for warning in result.metadata["runtime_support"]["unsupported_runtime_warnings"]] == [
"mention_target_missing",
"mention_target_missing",
@@ -1629,37 +1628,17 @@ def test_build_config_layer_config_excludes_missing_assets_from_runtime():
]
-# ── ENG-635: ask_human layer gating + feature manifest ───────────────────────
-
-
-def test_build_ask_human_layer_config_gated_on_human_contacts():
- from dify_agent.layers.ask_human import DifyAskHumanLayerConfig
-
- from core.workflow.nodes.agent_v2.runtime_request_builder import build_ask_human_layer_config
-
- # no human involvement configured -> tool stays off
- assert build_ask_human_layer_config(AgentSoulConfig()) is None
-
- soul = AgentSoulConfig.model_validate(
- {"human": {"contacts": [{"id": "c-1", "name": "David", "email": "[email protected]", "channel": "email"}]}}
- )
- config = build_ask_human_layer_config(soul)
- assert isinstance(config, DifyAskHumanLayerConfig)
- assert config.enabled is True
-
-
-def test_feature_manifest_marks_human_supported_when_configured():
+def test_feature_manifest_marks_human_reserved_when_configured():
from core.workflow.nodes.agent_v2.runtime_feature_manifest import build_runtime_feature_manifest
soul = AgentSoulConfig.model_validate(
{"human": {"contacts": [{"id": "c-1", "name": "David", "email": "[email protected]", "channel": "email"}]}}
)
manifest = build_runtime_feature_manifest(soul)
- assert "human" in manifest["supported"]
- assert "human" not in manifest["reserved"]
- assert manifest["reserved_status"]["human"] == "supported_by_ask_human_hitl"
- # configured human no longer produces a "not executed" warning
- assert all("human" not in w["section"] for w in manifest["unsupported_runtime_warnings"])
+ assert "human" not in manifest["supported"]
+ assert "human" in manifest["reserved"]
+ assert manifest["reserved_status"]["human"] == "reserved_not_executed"
+ assert any("human" in w["section"] for w in manifest["unsupported_runtime_warnings"])
def test_feature_manifest_marks_knowledge_supported_without_warning_when_configured():
diff --git a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py
index e18e36a2adb..9ace4b35338 100644
--- a/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py
+++ b/api/tests/unit_tests/core/workflow/nodes/agent_v2/test_session_store.py
@@ -5,9 +5,7 @@ from types import SimpleNamespace
from unittest.mock import MagicMock
import pytest
-from agenton.compositor import CompositorSessionSnapshot
-from agenton.compositor.schemas import LayerSessionSnapshot
-from agenton.layers.base import LifecycleState
+from dify_agent.protocol.snapshot import SessionSnapshot
from sqlalchemy import Engine, event, func, select
from sqlalchemy.orm import Session, sessionmaker
@@ -197,15 +195,7 @@ def test_conversation_scope_reuses_existing_binding_on_later_turn(
monkeypatch: pytest.MonkeyPatch,
sqlite_session: Session,
) -> None:
- prior_snapshot = CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(
- name="history",
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={"turn": 1},
- )
- ]
- )
+ prior_snapshot = SessionSnapshot(layers={"history": {"turn": 1}})
workspace = AgentWorkspace(
id="workspace-conversation",
tenant_id="tenant-1",
@@ -437,7 +427,7 @@ def test_save_snapshot_targets_binding(sqlite_session: Session) -> None:
binding = _binding_row()
sqlite_session.add_all([_workspace_row(), binding])
sqlite_session.commit()
- snapshot = CompositorSessionSnapshot(layers=[])
+ snapshot = SessionSnapshot(layers={})
WorkflowAgentWorkspaceStore().save_active_snapshot(
scope=_scope(),
diff --git a/api/tests/unit_tests/services/test_human_input_service.py b/api/tests/unit_tests/services/test_human_input_service.py
index 57a3899a90a..840ac115c64 100644
--- a/api/tests/unit_tests/services/test_human_input_service.py
+++ b/api/tests/unit_tests/services/test_human_input_service.py
@@ -370,36 +370,6 @@ def test_submit_form_by_token_calls_repository_and_enqueue(
enqueue_spy.assert_called_once_with(sample_form_record.workflow_run_id)
-def test_submit_form_by_token_enqueues_agent_app_resume_for_conversation_form(
- form_repository: Callable[[HumanInputFormRecord | None], HumanInputFormSubmissionRepository],
- sample_form_record: HumanInputFormRecord,
- unbound_session_factory: sessionmaker[Session],
- mocker: MockerFixture,
-) -> None:
- # ENG-635: a conversation-owned (Agent v2 chat) form routes to the chat
- # resume, not the workflow resume.
- conversation_record = dataclasses.replace(
- sample_form_record,
- workflow_run_id=None,
- conversation_id="conv-1",
- )
- repo = form_repository(conversation_record)
- service = HumanInputService(unbound_session_factory, form_repository=repo)
- workflow_enqueue_spy = mocker.patch.object(service, "enqueue_resume")
- chat_enqueue_spy = mocker.patch.object(service, "enqueue_agent_app_resume")
-
- service.submit_form_by_token(
- recipient_type=RecipientType.STANDALONE_WEB_APP,
- form_token="token",
- selected_action_id="submit",
- form_data={"field": "value"},
- submission_end_user_id="end-user-id",
- )
-
- chat_enqueue_spy.assert_called_once_with(conversation_id="conv-1", form_id=conversation_record.form_id)
- workflow_enqueue_spy.assert_not_called()
-
-
def test_submit_form_by_token_skips_enqueue_for_delivery_test(
form_repository: Callable[[HumanInputFormRecord | None], HumanInputFormSubmissionRepository],
sample_form_record: HumanInputFormRecord,
diff --git a/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py b/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py
index 3b320f4a0ec..1b69892571b 100644
--- a/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py
+++ b/api/tests/unit_tests/tasks/test_human_input_timeout_tasks.py
@@ -250,49 +250,3 @@ def test_check_and_handle_human_input_timeouts_omits_global_filter_when_disabled
global_timeout_handler.assert_not_called()
sqlite_session.refresh(old_unexpired_form)
assert old_unexpired_form.status == HumanInputFormStatus.WAITING
-
-
[email protected]("sqlite_session", [(HumanInputForm,)], indirect=True)
-def test_check_and_handle_human_input_timeouts_routes_conversation_owned_form_to_agent_app_resume(
- monkeypatch: pytest.MonkeyPatch,
- sqlite_task_database: None,
- sqlite_session: Session,
-):
- # ENG-635 (review): a conversation-owned Agent v2 chat ask_human form has no
- # workflow_run_id. On timeout it must enqueue the Agent App resume (so the
- # timeout is threaded back as the ask_human result), instead of asserting on
- # workflow_run_id — which previously raised and was swallowed by the except.
- now = datetime(2025, 1, 1, 12, 0, 0)
- monkeypatch.setattr(task_module, "naive_utc_now", lambda: now)
- apply_config_overrides(monkeypatch, HUMAN_INPUT_GLOBAL_TIMEOUT_SECONDS=3600)
-
- form = _build_form(
- form_id="form-chat",
- form_kind=HumanInputFormKind.RUNTIME,
- created_at=now - timedelta(minutes=5),
- expiration_time=now - timedelta(seconds=1),
- workflow_run_id=None,
- conversation_id="conv-1",
- node_id="agent",
- )
- sqlite_session.add(form)
- sqlite_session.commit()
-
- repo = HumanInputFormSubmissionRepository()
- mark_timeout_spy = MagicMock(wraps=repo.mark_timeout)
- monkeypatch.setattr(repo, "mark_timeout", mark_timeout_spy)
- service = _FakeService()
- monkeypatch.setattr(task_module, "HumanInputFormSubmissionRepository", lambda: repo)
- monkeypatch.setattr(task_module, "HumanInputService", lambda *_args, **_kwargs: service)
- monkeypatch.setattr(task_module, "_handle_global_timeout", lambda **_kwargs: None)
-
- task_module.check_and_handle_human_input_timeouts(limit=100)
-
- # Node timeout (conversation forms are never "global"), routed to Agent App resume.
- mark_timeout_spy.assert_called_once_with(
- form_id="form-chat", timeout_status=HumanInputFormStatus.TIMEOUT, reason="node_timeout"
- )
- assert service.agent_app_resumed == [("conv-1", "form-chat")]
- assert service.enqueued == []
- sqlite_session.refresh(form)
- assert form.status == HumanInputFormStatus.TIMEOUT
diff --git a/api/tests/unit_tests/tasks/test_resume_agent_app_task.py b/api/tests/unit_tests/tasks/test_resume_agent_app_task.py
deleted file mode 100644
index ce063d3a6bb..00000000000
--- a/api/tests/unit_tests/tasks/test_resume_agent_app_task.py
+++ /dev/null
@@ -1,258 +0,0 @@
-"""Unit tests for the ``resume_agent_app_execution`` Celery task (ENG-635)."""
-
-from __future__ import annotations
-
-from collections.abc import Iterator
-from datetime import UTC, datetime, timedelta
-from uuid import uuid4
-
-import pytest
-from pytest_mock import MockerFixture
-from sqlalchemy.orm import Session, scoped_session, sessionmaker
-
-from core.app.entities.app_invoke_entities import InvokeFrom
-from core.workflow.nodes.human_input.enums import HumanInputFormKind, HumanInputFormStatus
-from models.account import Account, Tenant, TenantAccountJoin, TenantAccountRole
-from models.enums import ConversationFromSource, EndUserType
-from models.enums import InvokeFrom as StoredInvokeFrom
-from models.human_input import HumanInputForm
-from models.model import App, AppMode, Conversation, EndUser
-from tasks.app_generate import resume_agent_app_task as mod
-from tests.unit_tests.model_factories import make_app, make_conversation
-
-MODULE = "tasks.app_generate.resume_agent_app_task"
-
-
-def task_session(mocker: MockerFixture, sqlite_session_factory: sessionmaker[Session]) -> Iterator[Session]:
- """Bind the task's Flask-SQLAlchemy session proxy to the shared SQLite database."""
- registry = scoped_session(sqlite_session_factory)
- mocker.patch.object(mod.db, "session", registry)
- session = registry()
- yield session
- registry.remove()
-
-
-def _app(*, app_id: str, tenant_id: str) -> App:
- return make_app(
- app_id=app_id,
- tenant_id=tenant_id,
- name="Agent app",
- mode=AppMode.AGENT_CHAT,
- icon_type=None,
- enable_site=False,
- enable_api=False,
- )
-
-
-def _conversation(
- *,
- conversation_id: str,
- app_id: str,
- account_id: str | None = None,
- end_user_id: str | None = None,
- invoke_from: StoredInvokeFrom = StoredInvokeFrom.WEB_APP,
-) -> Conversation:
- return make_conversation(
- conversation_id=conversation_id,
- app_id=app_id,
- mode=AppMode.AGENT_CHAT,
- name="Agent conversation",
- inputs={},
- invoke_from=invoke_from,
- from_source=ConversationFromSource.API,
- from_account_id=account_id,
- from_end_user_id=end_user_id,
- )
-
-
-def _form(*, form_id: str, conversation_id: str, app_id: str) -> HumanInputForm:
- return HumanInputForm(
- id=form_id,
- tenant_id=str(uuid4()),
- app_id=app_id,
- workflow_run_id=None,
- conversation_id=conversation_id,
- form_kind=HumanInputFormKind.RUNTIME,
- node_id="ask-human",
- form_definition="{}",
- rendered_content="Question",
- status=HumanInputFormStatus.WAITING,
- expiration_time=datetime.now(UTC).replace(tzinfo=None) + timedelta(hours=1),
- )
-
-
-def _seed_account(session: Session, *, tenant_id: str, account_id: str) -> Account:
- tenant = Tenant(name="Tenant")
- tenant.id = tenant_id
- account = Account(name="Account", email="[email protected]")
- account.id = account_id
- join = TenantAccountJoin(
- tenant_id=tenant_id,
- account_id=account_id,
- current=True,
- role=TenantAccountRole.NORMAL,
- )
- session.add_all([tenant, account, join])
- return account
-
-
-def test_resume_happy_path_account_user_sets_tenant_and_runs(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id, account_id = (str(uuid4()) for _ in range(5))
- app = _app(app_id=app_id, tenant_id=tenant_id)
- account = _seed_account(task_session, tenant_id=tenant_id, account_id=account_id)
- conversation = _conversation(conversation_id=conversation_id, app_id=app_id, account_id=account_id)
- task_session.add_all([app, conversation, _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id)])
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
-
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
-
- call = generator.return_value.resume_after_form_submission.call_args
- assert call is not None
- assert call.kwargs["conversation_id"] == conversation_id
- assert call.kwargs["form_id"] == form_id
- assert call.kwargs["user"] is account
- assert call.kwargs["app_model"] is app
- assert call.kwargs["invoke_from"] == InvokeFrom.WEB_APP
- assert isinstance(call.kwargs["session"], Session)
- assert account.current_tenant_id == tenant_id
-
-
-def test_resume_end_user_path(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id, end_user_id = (str(uuid4()) for _ in range(5))
- app = _app(app_id=app_id, tenant_id=tenant_id)
- end_user = EndUser(
- id=end_user_id,
- tenant_id=tenant_id,
- app_id=app_id,
- type=EndUserType.BROWSER,
- name="End user",
- session_id="browser-session",
- )
- task_session.add_all(
- [
- app,
- end_user,
- _conversation(conversation_id=conversation_id, app_id=app_id, end_user_id=end_user_id),
- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),
- ]
- )
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
-
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
-
- assert generator.return_value.resume_after_form_submission.call_args.kwargs["user"] is end_user
-
-
-def test_resume_preserves_debugger_invoke_from(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id, account_id = (str(uuid4()) for _ in range(5))
- app = _app(app_id=app_id, tenant_id=tenant_id)
- _seed_account(task_session, tenant_id=tenant_id, account_id=account_id)
- task_session.add_all(
- [
- app,
- _conversation(
- conversation_id=conversation_id,
- app_id=app_id,
- account_id=account_id,
- invoke_from=StoredInvokeFrom.DEBUGGER,
- ),
- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),
- ]
- )
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
-
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
-
- assert generator.return_value.resume_after_form_submission.call_args.kwargs["invoke_from"] == InvokeFrom.DEBUGGER
-
-
[email protected]("task_session")
-def test_resume_returns_when_form_missing(mocker: MockerFixture) -> None:
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- mod.resume_agent_app_execution(conversation_id=str(uuid4()), form_id=str(uuid4()))
- generator.assert_not_called()
-
-
-def test_resume_returns_on_conversation_mismatch(mocker: MockerFixture, task_session: Session) -> None:
- app_id, form_id = str(uuid4()), str(uuid4())
- task_session.add(_form(form_id=form_id, conversation_id=str(uuid4()), app_id=app_id))
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- mod.resume_agent_app_execution(conversation_id=str(uuid4()), form_id=form_id)
- generator.assert_not_called()
-
-
-def test_resume_returns_when_app_missing(mocker: MockerFixture, task_session: Session) -> None:
- conversation_id, form_id = str(uuid4()), str(uuid4())
- task_session.add(_form(form_id=form_id, conversation_id=conversation_id, app_id=str(uuid4())))
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
- generator.assert_not_called()
-
-
-def test_resume_returns_when_conversation_missing(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id = (str(uuid4()) for _ in range(4))
- task_session.add_all(
- [
- _app(app_id=app_id, tenant_id=tenant_id),
- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),
- ]
- )
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
- generator.assert_not_called()
-
-
-def test_resume_returns_when_no_user_resolvable(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id = (str(uuid4()) for _ in range(4))
- task_session.add_all(
- [
- _app(app_id=app_id, tenant_id=tenant_id),
- _conversation(conversation_id=conversation_id, app_id=app_id),
- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),
- ]
- )
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
- generator.assert_not_called()
-
-
-def test_resume_returns_when_account_id_set_but_account_gone(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id = (str(uuid4()) for _ in range(4))
- task_session.add_all(
- [
- _app(app_id=app_id, tenant_id=tenant_id),
- _conversation(conversation_id=conversation_id, app_id=app_id, account_id=str(uuid4())),
- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),
- ]
- )
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
- generator.assert_not_called()
-
-
-def test_resume_swallows_generator_exception(mocker: MockerFixture, task_session: Session) -> None:
- tenant_id, app_id, conversation_id, form_id, account_id = (str(uuid4()) for _ in range(5))
- _seed_account(task_session, tenant_id=tenant_id, account_id=account_id)
- task_session.add_all(
- [
- _app(app_id=app_id, tenant_id=tenant_id),
- _conversation(conversation_id=conversation_id, app_id=app_id, account_id=account_id),
- _form(form_id=form_id, conversation_id=conversation_id, app_id=app_id),
- ]
- )
- task_session.commit()
- generator = mocker.patch(f"{MODULE}.AgentAppGenerator")
- generator.return_value.resume_after_form_submission.side_effect = RuntimeError("boom")
-
- mod.resume_agent_app_execution(conversation_id=conversation_id, form_id=form_id)
-
- generator.return_value.resume_after_form_submission.assert_called_once()
diff --git a/api/uv.lock b/api/uv.lock
index db7ac88a925..32b72147fea 100644
--- a/api/uv.lock
+++ b/api/uv.lock
@@ -1,5 +1,5 @@
version = 1
-revision = 3
+revision = 5
requires-python = "==3.13.*"
resolution-markers = [
"sys_platform == 'win32'",
@@ -1363,8 +1363,8 @@ requires-dist = [
{ name = "openshell", marker = "extra == 'server'", specifier = ">=0.0.106,<0.1.0" },
{ name = "pydantic", specifier = ">=2.12.5,<2.13" },
{ name = "pydantic-ai-harness", specifier = ">=0.20.0,<0.21.0" },
- { name = "pydantic-ai-slim", specifier = ">=2.30.0,<3.0.0" },
- { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = ">=2.30.0,<3.0.0" },
+ { name = "pydantic-ai-slim", specifier = "==2.31.0" },
+ { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = "==2.31.0" },
{ name = "pydantic-settings", marker = "extra == 'server'", specifier = ">=2.12.0,<3.0.0" },
{ name = "redis", marker = "extra == 'server'", specifier = ">=7.4.0,<8.0.0" },
{ name = "typing-extensions", specifier = ">=4.12.2,<5.0.0" },
@@ -1392,6 +1392,7 @@ docs = [
name = "dify-api"
version = "1.17.1"
source = { virtual = "." }
+default-groups = ["kms", "storage", "tools", "trace-all", "vdb-all"]
dependencies = [
{ name = "aliyun-log-python-sdk" },
{ name = "azure-identity" },
diff --git a/dify-agent/README.md b/dify-agent/README.md
index 033974aa6ba..3cac71369aa 100644
--- a/dify-agent/README.md
+++ b/dify-agent/README.md
@@ -1,7 +1,8 @@
# Dify Agent
-Agenton documentation lives in [`docs/agenton/guide/index.md`](docs/agenton/guide/index.md) and
-[`docs/agenton/examples/index.md`](docs/agenton/examples/index.md).
+Dify Agent runs Pydantic AI with native capabilities and toolsets. Module
+configuration and session state are JSON data; infrastructure services and
+operation resources have explicit owners.
-Dify Agent runtime documentation lives in [`docs/dify-agent/index.md`](docs/dify-agent/index.md).
-Build all docs with `make docs` from this directory.
+See [runtime documentation](docs/dify-agent/index.md) and the
+[operations guide](docs/dify-agent/guide/index.md). Run `make docs` to build docs.
diff --git a/dify-agent/docs/agenton/examples/index.md b/dify-agent/docs/agenton/examples/index.md
deleted file mode 100644
index 61487f5a11e..00000000000
--- a/dify-agent/docs/agenton/examples/index.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# Agenton examples
-
-The Agenton examples live under `examples/agenton/agenton_examples` and are kept
-importable as a package so documentation can reference real source files.
-
-## Basics
-
-```snippet {path="/examples/agenton/agenton_examples/basics.py"}
-```
-
-## Pydantic AI bridge
-
-```snippet {path="/examples/agenton/agenton_examples/pydantic_ai_bridge.py"}
-```
-
-## Session snapshots
-
-```snippet {path="/examples/agenton/agenton_examples/session_snapshot.py"}
-```
diff --git a/dify-agent/docs/agenton/guide/index.md b/dify-agent/docs/agenton/guide/index.md
deleted file mode 100644
index e9d322d7c8a..00000000000
--- a/dify-agent/docs/agenton/guide/index.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Agenton user guide
-
-Agenton composes reusable graph plans from `LayerNode`s and `LayerProvider`s.
-The core is state-only: a `Compositor` stores no live layer instances, clients,
-cleanup stacks, or run state. Each `Compositor.enter(...)` call creates a fresh
-`CompositorRun` with new layer instances, direct dependency bindings, lifecycle
-state, and an optional hydrated session snapshot.
-
-## Config and runtime state
-
-- **Graph config** is serializable topology: node `name`, provider `type`,
- dependency mappings, and metadata. `LayerNodeConfig` deliberately contains no
- layer config.
-- **Per-run layer config** is passed to `Compositor.enter(configs=...)` as a
- mapping keyed by node name. Providers validate each value with the layer's
- `config_type` before any factory runs.
-- **Runtime state** is serializable per-layer invocation state on
- `layer.runtime_state`. Session snapshots persist only lifecycle state and this
- model's JSON-safe data.
-- **Live Python resources** such as clients, files, sockets, or process handles
- stay outside Agenton core. Own them in application code or integration-specific
- context managers that wrap compositor entry.
-
-## Define a config-backed layer
-
-Use a `LayerConfig` model for per-run config and inherit from a typed layer family
-so `Layer.__init_subclass__` can infer schemas:
-
-```python {test="skip" lint="skip"}
-from dataclasses import dataclass
-
-from pydantic import ConfigDict
-from typing_extensions import Self, override
-
-from agenton.layers import LayerConfig, NoLayerDeps, PlainLayer
-
-
-class GreetingConfig(LayerConfig):
- prefix: str
-
- model_config = ConfigDict(extra="forbid")
-
-
-@dataclass(slots=True)
-class GreetingLayer(PlainLayer[NoLayerDeps, GreetingConfig]):
- type_id = "example.greeting"
-
- prefix: str
-
- @classmethod
- @override
- def from_config(cls, config: GreetingConfig) -> Self:
- return cls(prefix=config.prefix)
-
- @property
- @override
- def prefix_prompts(self) -> list[str]:
- return [self.prefix]
-```
-
-Omitted schema slots default to `EmptyLayerConfig` and `EmptyRuntimeState`.
-Lifecycle hooks are no-argument methods on the layer instance; use `self.deps`
-for dependencies and `self.runtime_state` for serializable mutable state.
-
-## Live resources
-
-Agenton does not own resource cleanup. Keep live resources in the surrounding
-application and pass them to capability methods explicitly:
-
-```python {test="skip" lint="skip"}
-@dataclass(slots=True)
-class ClientUserLayer(PlainLayer[NoLayerDeps]):
- def make_client_user(self, *, http_client: httpx.AsyncClient) -> ClientUser:
- return ClientUser(http_client)
-
-
-compositor = Compositor([LayerNode("client_user", ClientUserLayer)])
-async with httpx.AsyncClient() as http_client:
- async with compositor.enter() as run:
- layer = run.get_layer("client_user", ClientUserLayer)
- user = layer.make_client_user(http_client=http_client)
-```
-
-This keeps deterministic cleanup at the integration boundary and leaves Agenton
-snapshots limited to serializable runtime state.
-
-## Build a compositor
-
-Use providers for config-backed layers and pass per-run config at entry time:
-
-```python {test="skip" lint="skip"}
-from agenton.compositor import Compositor, CompositorConfig, LayerNodeConfig, LayerProvider
-from agenton_collections.layers.plain import PromptLayer, PromptLayerConfig
-
-
-providers = (
- LayerProvider.from_layer_type(PromptLayer),
- LayerProvider.from_layer_type(GreetingLayer),
-)
-compositor = Compositor.from_config(
- CompositorConfig(
- layers=[
- LayerNodeConfig(name="prompt", type="plain.prompt"),
- LayerNodeConfig(name="greeting", type="example.greeting"),
- ]
- ),
- providers=providers,
-)
-
-async with compositor.enter(
- configs={
- "prompt": PromptLayerConfig(user="Answer with examples."),
- "greeting": GreetingConfig(prefix="Hi"),
- }
-) as run:
- prompts = run.prompts
-```
-
-Use `LayerProvider.from_factory(...)` when construction needs Python objects or
-callables. Provider factories receive only validated config and must return a
-fresh layer instance for every invocation. For node-specific construction with
-`Compositor.from_config`, pass a `node_providers={"node_name": provider}` mapping
-to override the provider selected by type id for that node.
-
-## Dependencies
-
-Layer dependencies bind direct layer instances onto `self.deps` for one run.
-Dependency mappings use dependency field names as keys and compositor node names
-as values:
-
-```python {test="skip" lint="skip"}
-class ModelDeps(LayerDeps):
- plugin: PluginLayer
-
-
-@dataclass(slots=True)
-class ModelLayer(PlainLayer[ModelDeps]):
- def make_model(self) -> Model:
- return self.deps.plugin.make_provider()
-```
-
-Optional dependencies are assigned `None` when absent. Missing required
-dependencies, unknown dependency keys, and dependency targets with the wrong layer
-type fail before lifecycle hooks run.
-
-## System prompts, user prompts, and tools
-
-Layers expose four authoring surfaces:
-
-- `prefix_prompts`: system prompt fragments collected in layer order.
-- `suffix_prompts`: system prompt fragments collected in reverse layer order.
-- `user_prompts`: user-message fragments collected in layer order.
-- `tools`: tool entries collected in layer order.
-
-`PromptLayer` accepts `prefix`, `user`, and `suffix` config fields. Aggregation is
-available on the active `CompositorRun` as `run.prompts`, `run.user_prompts`, and
-`run.tools`. For pydantic-ai, import
-`agenton_collections.transformers.pydantic_ai.PYDANTIC_AI_TRANSFORMERS` and pass
-it to `Compositor(...)` or `Compositor.from_config(...)` so tagged layer items are
-converted to Pydantic AI prompt, user prompt, and tool values.
-
-## Session snapshot and restore
-
-Core Agenton run slots default to delete-on-exit. Call `run.suspend_on_exit()` or
-`run.suspend_layer_on_exit(name)` inside the active context when the next snapshot
-should be resumable:
-
-```python {test="skip" lint="skip"}
-async with compositor.enter(configs=configs) as run:
- run.suspend_on_exit()
-
-snapshot = run.session_snapshot
-async with compositor.enter(configs=configs, session_snapshot=snapshot) as restored_run:
- restored_layer = restored_run.get_layer("stateful", StatefulLayer)
-```
-
-`run.session_snapshot` is populated after context exit. Snapshots include ordered
-layer names, non-active lifecycle states, and JSON-safe runtime state only. Active
-state is rejected at the DTO boundary, and closed layers cannot be entered again.
-To resume, pass the snapshot to a later `Compositor.enter(...)` call with the same
-layer names and order.
-
-See also:
-
-- `examples/agenton/agenton_examples/basics.py`
-- `examples/agenton/agenton_examples/pydantic_ai_bridge.py`
-- `examples/agenton/agenton_examples/session_snapshot.py`
diff --git a/dify-agent/docs/agenton/index.md b/dify-agent/docs/agenton/index.md
deleted file mode 100644
index 2af61df2267..00000000000
--- a/dify-agent/docs/agenton/index.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Agenton documentation
-
-- [User guide](guide/index.md) explains how to compose layers, register config-backed
- plugins, use system/user prompts, and snapshot sessions.
diff --git a/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md b/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md
index e4a3593d986..69404705afe 100644
--- a/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md
+++ b/dify-agent/docs/dify-agent/concepts/run-lifecycle/index.md
@@ -1,197 +1,38 @@
-# Agent Run Lifecycle
+# Agent run lifecycle
-This page explains, from a caller's perspective, how an `agent run` relates to a
-`workflow run` and how callers control Agenton layer exit behavior with exit
-signals.
+The server validates current Config, restored State and module references before
+external operations. It creates fresh native Capability/Toolset instances and
+runs Pydantic AI with a per-run Deps object. Current prompts and instructions are
+built from that run's config.
-## Relationship between agent runs and workflow runs
+Native `wrap_run` scopes acquire operation resources and clean them in `finally`.
+Runtime acquires a lease; Shell bootstraps once and removes tracked jobs on exit;
+Config pulls mentioned assets on successful first initialization. Initialization
+flags are written only after successful setup, so failures can retry. The API's
+workflow terminal events own Workspace retirement and physical resource collection.
-A `workflow run` is one full workflow execution. An `agent run` is one Agent
-execution started by an Agent node while the workflow is running. They are not a
-one-to-one mapping: one `workflow run` often contains multiple `agent run`s.
+The runner saves captured conversation history in its outer `finally`, strips
+transient instructions and marks unexecuted trailing tool calls interrupted.
+If no messages were captured, restored history remains intact. Compaction rewrites
+are included. A terminal state snapshot is built after capability cleanup for
+success, failure and cancellation.
-### First entry into an Agent node
-
-When a `workflow run` first reaches an Agent node, the caller starts the first
-`agent run` for that node.
-
-The `agent run` enters the layers defined in its composition:
-
-- If the request does not include `session_snapshot`, each layer enters with a
- fresh state and initializes its own runtime state.
-- If the request includes a previously returned `session_snapshot`, each layer
- restores its runtime state from that snapshot and continues from there.
-
-After entering layers, the Agent runs the LLM and tool calls until the current
-`agent run` reaches a terminal result. This means the `agent run` has ended; it
-does not necessarily mean the outer workflow has ended.
-
-### Ending with a `final_output` tool call
-
-If the Agent ends with a `final_output` tool call, the Agent node has produced
-its final output for this pass. The caller should read the terminal output of the
-current `agent run` and let the `workflow run` continue to downstream nodes.
-
-The current `agent run` has ended, but the returned `session_snapshot` can still
-be saved. If the same `workflow run` may enter the same Agent session again, the
-caller should keep using that snapshot.
-
-### Ending with a human tool call
-
-If the Agent ends with a human tool call, the Agent needs human input before the
-business process can continue. A common misconception is to treat this as a
-paused agent run. **Agent runs do not have a pause state.** With a human tool, the
-current `agent run` has ended; the outer `workflow run` is what should be paused.
-
-The caller should handle this flow as follows:
-
-1. Read the current `agent run` result and detect `deferred_tool_call` on the
- terminal `run_succeeded` event.
-2. Enter workflow HITL handling and pause graphon.
-3. Wait for the human input to be completed.
-4. When resuming the workflow, start a second `agent run` on the same Agent node
- with the previous `session_snapshot`, matching composition, and
- `deferred_tool_results` keyed by the original tool call id.
-5. Keep the history layer active so Dify Agent can match the result to the
- pending tool call stored in the previous run's message history.
-
-In other words, a human tool does not mean “pause this agent run until it is
-resumed.” It means “this agent run ended with a result that requires human
-input.” After the caller completes HITL handling, it should create a new
-`agent run` using the same history/session snapshot to continue.
-
-### Entering another Agent node
-
-When the same `workflow run` continues and reaches another Agent node, it starts
-another `agent run`. That next Agent node may be a different Agent, or it may be
-the same Agent reused by a roaster.
-
-Therefore, callers should save and pass `session_snapshot` by Agent session, not
-assume that one `workflow run` has only one `agent run`.
-
-## Agent run exit signals
-
-When an `agent run` ends, Dify Agent exits the layers that were entered by the
-current run. Callers control whether each layer is suspended or deleted through
-`CreateRunRequest.on_exit`.
-
-Exit signals control the **layer lifecycle state**, not the execution state of an
-`agent run`. The default policy is `suspend`, so any run that enters and exits its
-compositor context can return a reusable `session_snapshot`, including failed or
-cancelled runs. Failures or cancellations before entry have no new snapshot.
-
-### Default: suspend layers
-
-If a request does not explicitly set `on_exit`, it is equivalent to:
+Snapshot v2 stores only JSON state:
```json
-{
- "on_exit": {
- "default": "suspend",
- "layers": {}
- }
-}
+{"schema_version": 2, "layers": {"history": {"messages": []}}}
```
-This means every entered layer exits as `suspended` and is written into the
-returned `session_snapshot`. The caller can submit that snapshot in the next
-`agent run` to resume those layers.
-
-For normal Agent execution inside a workflow, including both `final_output` and
-human-tool endings, callers should keep the default suspend policy unless they
-know the Agent session will never be resumed.
-
-### Delete layers when the workflow run ends
-
-When the whole `workflow run` has ended, the caller should start one more cleanup
-`agent run`:
-
-- Reuse the last available `session_snapshot`.
-- Omit the LLM layer, because this run is only for entering and cleaning existing
- state; it does not need to call the model again.
-- Exit layers with the `delete` signal.
-
-The cleanup request should use an exit signal like this:
-
-```json
-{
- "on_exit": {
- "default": "delete",
- "layers": {}
- }
-}
-```
-
-After this run, the corresponding layers exit through the delete path. A snapshot
-returned after deletion should not be used to resume the Agent session again.
-
-### Override selected layers
-
-The caller can also suspend by default while deleting only selected layers:
-
-```json
-{
- "on_exit": {
- "default": "suspend",
- "layers": {
- "temporary_context": "delete"
- }
- }
-}
-```
-
-Only `temporary_context` exits with `delete`; all other active layers exit with
-the default `suspend` behavior.
-
-## Exit signal API reference
-
-Fields related to exit control in `CreateRunRequest`:
-
-| Field | Type | Required | Meaning |
-| --- | --- | --- | --- |
-| `session_snapshot` | `CompositorSessionSnapshot \| None` | no | The session snapshot returned by the previous `agent run`. It resumes the same Agent session. |
-| `on_exit` | `LayerExitSignals` | no | The exit policy used when this `agent run` exits layers. If omitted, all active layers are suspended by default. |
-
-`LayerExitSignals` has this structure:
-
-| Field | Type | Default | Meaning |
-| --- | --- | --- | --- |
-| `default` | `"suspend" \| "delete"` | `"suspend"` | Exit intent for layers not explicitly listed in `layers`. |
-| `layers` | `dict[str, "suspend" \| "delete"]` | `{}` | Per-layer exit intent overrides by layer name. Each key must refer to a layer name in the current composition. |
-
-Exit intent semantics:
-
-| Exit intent | Layer exit state | Effect |
-| --- | --- | --- |
-| `suspend` | `suspended` | Keep the layer runtime state and make the returned `session_snapshot` usable by a later `agent run`. |
-| `delete` | `closed` | Delete/close the layer context. The corresponding layer snapshot should not be resumed again. |
-
-Python DTO example:
-
-```python {test="skip" lint="skip"}
-from agenton.layers import ExitIntent
-from dify_agent.protocol import CreateRunRequest, LayerExitSignals
-
-
-request = CreateRunRequest(
- composition=composition,
- session_snapshot=previous_snapshot,
- on_exit=LayerExitSignals(
- default=ExitIntent.SUSPEND,
- layers={
- "temporary_context": ExitIntent.DELETE,
- },
- ),
-)
-```
-
-Notes:
-
-- `on_exit` only controls layer exit behavior; it does not cancel an `agent run`.
-- Agent runs do not have a pause state. Human-tool waiting is handled by the
- outer workflow/HITL flow.
-- Keys in `on_exit.layers` must refer to layer names in the current composition.
-- Use `suspend` and save the returned `session_snapshot` when the same Agent
- session needs to continue later.
-- After the whole `workflow run` ends, start one more cleanup run without an LLM
- layer and use `delete`.
+Configurations, clients, lease handles, tokens, models and lifecycle enums are
+excluded. State is keyed by name, so instruction order does not constrain resume;
+known optional modules can be added or removed. The API resubmits current Config
+and retains session ownership through `AgentWorkspaceBinding.session_snapshot`.
+All snapshot readers use `SessionSnapshot` validation. Its `migrate_snapshot`
+validator dispatches v1 (including unversioned legacy lists) to the data-only
+`migrate_snapshot_v1_to_v2` helper. V2 is validated directly; unknown explicit
+versions are rejected. Reading converts data in memory without updating stored
+JSON; the API saves the terminal v2 snapshot through its existing session owner.
+Known legacy names map to their meaningful State and removed AskHuman slots are
+discarded. Their unanswered tool calls are marked interrupted so native history
+repair closes them before the first new user turn. All runs use the native runner.
+Unknown legacy names and malformed state are rejected.
diff --git a/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md b/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md
index 8f2ae9fc2b5..cecde67ffe9 100644
--- a/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md
+++ b/dify-agent/docs/dify-agent/concepts/runtime-resources/index.md
@@ -10,7 +10,7 @@ Dify separates persistent product resources from request-time execution:
- a **RuntimeLease** is operation-scoped access to the physical Binding.
`AgentWorkspaceBinding.id` is the participant, materialized Home, and persisted
-Agenton session identity. `agent_id` identifies the source Agent. The same
+module session identity. `agent_id` identifies the source Agent. The same
Agent can therefore have multiple active Bindings in one Workspace:
each has an independent Home and session, while all may share Workspace files.
@@ -19,11 +19,11 @@ physical representation. For example, current E2B maps one Binding and its
Workspace to one E2B resource, while Local can attach multiple materialized
Homes to one shared Workspace.
-## Runtime layer graph
+## Runtime modules
Agent requests do not expose separate Home, Workspace, or Sandbox layers. Dify
API resolves the Binding selected by the product flow and sends its opaque
-backend ref to the `dify.runtime` layer:
+backend ref to the `runtime` module:
```mermaid
flowchart LR
@@ -35,13 +35,13 @@ flowchart LR
RT --> SH
```
-`DifyRuntimeLayer` calls the selected `ExecutionBindingBackend.acquire()` when
-its resource context opens and `release()` when the operation ends. It exposes
-the resulting `RuntimeLease` only while that context is active. The layer does
+`runtime.Capability` calls the selected `ExecutionBindingBackend.acquire()` when
+its native `wrap_run` scope opens and `release()` when the operation ends. It exposes
+the resulting `RuntimeLease` only while that context is active. The module does
not create, retire, or destroy persistent resources, and it stores no backend
-SDK object in an Agenton session snapshot.
+SDK object in an module session snapshot.
-The Shell layer consumes `RuntimeLease.commands` and `RuntimeLease.layout`. It
+The Shell module consumes `RuntimeLease.commands` and `RuntimeLease.layout`. It
tracks only request-local shell job ids and offsets.
Closing a run clears that job state; it does not retire the Binding.
@@ -56,7 +56,7 @@ Dify API is the lifecycle ledger. It stores three resource records:
| `agent_workspace_bindings` | One materialized participant, private Home, and resumable session attached to a Workspace. | `backend_binding_ref` |
Backend refs are opaque strings interpreted only by the selected backend
-adapter. Dify API stores the latest Agenton session snapshot on the Binding, but
+adapter. Dify API stores the latest module session snapshot on the Binding, but
it does not serialize `RuntimeLease`, SDK clients, credentials, or temporary
access tokens.
@@ -99,7 +99,6 @@ composition contains:
```json
{
"name": "runtime",
- "type": "dify.runtime",
"config": {"backend_binding_ref": "opaque-backend-binding-ref"}
}
```
@@ -227,7 +226,7 @@ remain independently configurable. Runtime resources pause on timeout, but this
resource setting does not own the Agent run terminal state. It is not a retention
TTL and does not delete paused resources or immutable snapshots.
-See the [Shell layer](../../user-manual/shell-layer/index.md) for request
+See the [Shell module](../../user-manual/shell-layer/index.md) for request
composition, the [Operations Guide](../../guide/index.md) for Local and E2B
validation, and the [OpenShell guide](../../guide/openshell.md) for OpenShell
configuration and validation.
diff --git a/dify-agent/docs/dify-agent/examples/index.md b/dify-agent/docs/dify-agent/examples/index.md
index 8624dc790e2..b004f4b33af 100644
--- a/dify-agent/docs/dify-agent/examples/index.md
+++ b/dify-agent/docs/dify-agent/examples/index.md
@@ -1,8 +1,8 @@
# Dify Agent examples
-These examples live under `examples/dify_agent/dify_agent_examples`. They are
-separated from Agenton examples because they depend on Dify Agent runtime services
-such as the FastAPI server, Redis, or the plugin daemon.
+These examples live under `examples/dify_agent/dify_agent_examples`. They use
+registered modules and depend on the Agent server, Redis, Dify API, and plugin
+daemon settings described in the operations guide.
## Run a Dify plugin-daemon backed model
diff --git a/dify-agent/docs/dify-agent/get-started/index.md b/dify-agent/docs/dify-agent/get-started/index.md
index c2db758c454..459984e2056 100644
--- a/dify-agent/docs/dify-agent/get-started/index.md
+++ b/dify-agent/docs/dify-agent/get-started/index.md
@@ -1,263 +1,25 @@
-# Get started with Dify Agent
-
-This guide walks through the smallest end-to-end path for the current Dify Agent
-runtime: install dependencies, configure the server, start it, then use the Python
-client to create one plugin-daemon-backed run.
-
-## Prerequisites
-
-Install or prepare:
-
-- Python 3.13 or newer
-- `uv`
-- Redis
-- a reachable Dify plugin daemon
-- a plugin/provider already available through that plugin daemon, such as
- `langgenius/openai`
-
-## Install dependencies
-
-From the repository root, enter the `dify-agent` package and install all extras
-and dependency groups:
-
-```bash
-cd dify-agent
-uv sync --all-extras --all-groups
-```
-
-Only the `server` extra is required to run the API server, but installing all
-extras and groups gives you the local test, docs, and server dependencies in one
-environment.
-
-## Start Redis
-
-Skip this step if you already have a reachable Redis instance.
-
-```bash
-docker run -d \
- --name dify-agent-redis \
- -p 6379:6379 \
- redis:7-alpine
-```
-
-## Configure the server
-
-Create or update `.env` in the `dify-agent` directory:
-
-```bash
-cat > .env <<'EOF'
-DIFY_AGENT_REDIS_URL=redis://localhost:6379/0
-DIFY_AGENT_REDIS_PREFIX=dify-agent
-
-DIFY_AGENT_PLUGIN_DAEMON_URL=http://localhost:5002
-DIFY_AGENT_PLUGIN_DAEMON_API_KEY=replace-with-plugin-daemon-server-key
-
-DIFY_AGENT_INNER_API_URL=http://localhost:5001
-DIFY_AGENT_INNER_API_KEY=replace-with-dify-inner-api-key-for-plugin
-EOF
-```
-
-The minimum settings are:
-
-- `DIFY_AGENT_REDIS_URL`: Redis connection URL used for run records and event
- streams.
-- `DIFY_AGENT_REDIS_PREFIX`: Redis key prefix for this server.
-- `DIFY_AGENT_PLUGIN_DAEMON_URL`: base URL for the Dify plugin daemon.
-- `DIFY_AGENT_PLUGIN_DAEMON_API_KEY`: API key sent by the server to the plugin
- daemon. In a Dify Docker setup this is usually the value previously configured
- as `PLUGIN_DAEMON_KEY`.
-- `DIFY_AGENT_INNER_API_URL`: Dify API service root for `/inner/api/...` calls.
-- `DIFY_AGENT_INNER_API_KEY`: API key sent to Dify API inner plugin endpoints.
- In Docker this should match `PLUGIN_DIFY_INNER_API_KEY`, which maps to Dify
- API `INNER_API_KEY_FOR_PLUGIN`.
-
-See `.example.env` for the full server settings template.
-
-If you plan to run `dify.shell`, select a coherent Home Snapshot and Execution
-Binding backend. A standalone Local server normally uses:
-
-```env
-DIFY_AGENT_RUNTIME_BACKEND=local
-DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT=http://127.0.0.1:5004
-DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN=
-# Optional when shellctl runs directly on a host without /home/dify:
-# DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT=/tmp/dify-agent/materialized-homes
-# DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT=/tmp/dify-agent/workspaces
-# DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT=/tmp/dify-agent/home-snapshots
-```
-
-E2B requires `DIFY_AGENT_E2B_API_KEY` and defaults to the prepared
-`difys-default-team/dify-agent-local-sandbox` template. The E2B active timeout
-pauses the physical resource behind a Binding; it is not a retention TTL.
-Enterprise supports Bindings created from its deployment-default Home.
-Immutable Home Snapshot creation and materialization remain unsupported there.
-
-A shell-enabled request includes Execution Context, `dify.runtime`, and
-`dify.shell`. Dify API creates or resolves the specific persistent Binding for
-the request's product context;
-`DifyRuntimeLayerConfig.backend_binding_ref` carries only that opaque ref and
-opens a new operation-scoped `RuntimeLease` for the run. When shell jobs need to
-call back with the `dify-agent` command, also set
-`DIFY_AGENT_STUB_API_BASE_URL` and the Sandbox-reachable Dify API base
-`DIFY_AGENT_SANDBOX_FILES_BASE_URL`. The supplied default configs include a
-development `DIFY_AGENT_SERVER_SECRET_KEY`, but production deployments should
-override it with a unique 32-byte base64url value as documented in
-`.example.env`.
-
-See [Runtime resources](../concepts/runtime-resources/index.md) for the layer
-graph and state ownership, and the [Operations Guide](../guide/index.md) for
-backend-specific configuration and validation commands.
-
-## Start the Dify Agent server
-
-For a normal local server process:
-
-```bash
-make serve
-```
-
-For development with uvicorn reload:
-
-```bash
-make dev
-```
-
-Both commands serve the API at:
-
-```text
-http://127.0.0.1:8000
-```
-
-The equivalent development command is:
-
-```bash
-uv run --extra server uvicorn dify_agent.server.app:app \
- --host 127.0.0.1 \
- --port 8000 \
- --reload
-```
-
-`ServerSettings` reads `.env` from the current `dify-agent` directory, or from
-`dify-agent/.env` when the command is run from the repository root.
-
-## Create a Python client example
-
-In another shell, keep working from the `dify-agent` directory. Create
-`run_dify_agent_client.py` with the example below, then replace the placeholder
-tenant, user, app, provider, and model values.
-
-```python {test="skip" lint="skip"}
-import asyncio
-import json
-import sys
-
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
-from dify_agent.client import Client
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DifyPluginLLMLayerConfig,
-)
-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, CreateRunRequest, RunComposition, RunLayerSpec
-
-
-API_BASE_URL = "http://127.0.0.1:8000"
-
-TENANT_ID = "replace-with-tenant-id"
-PLUGIN_ID = "langgenius/openai"
-USER_ID = "replace-with-user-id"
-APP_ID = "replace-with-app-id"
-
-# Keep these aligned with DIFY_AGENT_PROVIDER and DIFY_AGENT_MODEL_NAME in dify-agent/.env.
-MODEL_PROVIDER = "replace-with-provider-from-dify-agent-env"
-MODEL_NAME = "replace-with-model-from-dify-agent-env"
-
-SYSTEM_PROMPT = "You are a concise assistant."
-USER_PROMPT = "用一句话介绍 Dify Agent。"
-
-
-def build_request() -> CreateRunRequest:
- return CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- config=PromptLayerConfig(prefix=SYSTEM_PROMPT, user=USER_PROMPT),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id=TENANT_ID,
- user_id=USER_ID,
- user_from="account",
- app_id=APP_ID,
- agent_mode="single_step",
- invoke_from="debugger",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id=PLUGIN_ID,
- model_provider=MODEL_PROVIDER,
- model=MODEL_NAME,
- ),
- ),
- ],
- ),
- )
-
-
-async def main() -> int:
- async with Client(base_url=API_BASE_URL, stream_timeout=None) as client:
- run = await client.create_run(build_request())
- print(f"created run: {run.run_id}, status={run.status}")
-
- async for event in client.stream_events(run.run_id):
- print(event.model_dump_json(indent=2))
-
- if event.type == "run_succeeded":
- print("final output:")
- print(json.dumps(event.data.output, ensure_ascii=False, indent=2))
- return 0
-
- if event.type == "run_failed":
- print(f"run failed: {event.data.error}", file=sys.stderr)
- return 2
-
- return 0
-
-
-if __name__ == "__main__":
- raise SystemExit(asyncio.run(main()))
-```
-
-## Run the client example
-
-The server-side `.env` controls how Dify Agent reaches Dify API and the plugin
-daemon. The client example selects the tenant/user/app/plugin/provider/model;
-Dify API resolves model credentials at invocation time.
-
-Run the example from the `dify-agent` directory:
-
-```bash
-uv run python ./run_dify_agent_client.py
-```
-
-Set `MODEL_PROVIDER` and `MODEL_NAME` to the same values as
-`DIFY_AGENT_PROVIDER` and `DIFY_AGENT_MODEL_NAME` in `dify-agent/.env`.
-
-## Troubleshooting
-
-If the run fails, check these items first:
-
-1. Redis is running and reachable from the Dify Agent server.
-2. The Dify Agent server is listening on `127.0.0.1:8000`.
-3. `DIFY_AGENT_INNER_API_URL` points to the Dify API used by this environment.
-4. `DIFY_AGENT_INNER_API_KEY` matches Dify API's configured inner API key.
-5. `PLUGIN_ID`, `MODEL_PROVIDER`, and `MODEL_NAME` in the client example match
- a model provider configured for the selected tenant in Dify API.
+# Get started
+
+Create a run with `POST /runs`; poll `/runs/{run_id}` or consume its event stream.
+The composition schema version is 2. Each entry contains a registered `name` and
+current JSON `config`. Module identity comes from the server registry; there are
+no graph type/dependency fields or generic per-module exit policy.
+
+```json
+{
+ "composition": {
+ "schema_version": 2,
+ "layers": [
+ {"name": "execution_context", "config": {"tenant_id": "tenant", "agent_mode": "agent_app", "invoke_from": "service-api"}},
+ {"name": "prompt", "config": {"prefix": "Be helpful", "user": "Hello"}},
+ {"name": "history", "config": {}},
+ {"name": "llm", "config": {"execution_context": "execution_context", "plugin_id": "langgenius/openai", "model_provider": "openai", "model": "gpt-4o-mini"}}
+ ]
+ }
+}
+```
+
+Resume by including the previous terminal `session_snapshot` and submitting the
+current composition. `llm` is required, `history` and `output` are optional.
+Resource cleanup always happens at exit. Cancellation is a separate operation;
+its terminal event is published only after the owner run has cleaned up.
diff --git a/dify-agent/docs/dify-agent/guide/index.md b/dify-agent/docs/dify-agent/guide/index.md
index 6be5b103f4b..f7bf9b8fc61 100644
--- a/dify-agent/docs/dify-agent/guide/index.md
+++ b/dify-agent/docs/dify-agent/guide/index.md
@@ -345,12 +345,14 @@ Each run explicitly limits Pydantic AI to 500 model-request steps. Tool calls do
not have a separate count limit, but every model request used to continue the
tool loop consumes one of those steps.
-`DIFY_AGENT_RUN_TIMEOUT_SECONDS` additionally applies a wall-clock deadline only
-around Pydantic AI's `agent.run(...)`, including its model/tool loop and event
-handler. It does not include compositor entry, RuntimeLease acquisition, tool
-preparation, session snapshot generation, or resource exit. Expiry cancels the
-active run task, allows the compositor to release resources, and finalizes the
-run as failed with `error_type: "agent_run_limit_exceeded"`.
+`DIFY_AGENT_RUN_TIMEOUT_SECONDS` additionally applies a wall-clock deadline around
+native Pydantic AI's `agent.run(...)`. This includes capability entry, RuntimeLease
+acquisition, dynamic tool preparation, the model/tool loop, and the event handler.
+Request validation and agent assembly happen before this deadline. Expiry cancels
+the native run; capability scopes unwind and release resources before the runner
+generates the session snapshot and finalizes the run as failed with
+`error_type: "agent_run_limit_exceeded"`. History persistence, snapshot generation,
+and terminal finalization occur after native execution.
During FastAPI shutdown the scheduler rejects new runs, waits up to
`DIFY_AGENT_SHUTDOWN_GRACE_SECONDS` for active tasks, then cancels remaining tasks
@@ -387,33 +389,29 @@ terminal event type.
## Run inputs and session snapshots
-The API does not accept a top-level `user_prompt`. Submit a `RunComposition`
-whose Agenton layers provide user input. With the MVP provider set, use
-`plain.prompt` and its `config.user` field:
+Submit a `RunComposition` with registered module names and JSON Config. The
+`llm` model module is required and references an `execution_context` module.
+Prompt modules contribute instructions and `config.user` input:
```json
{
"composition": {
- "schema_version": 1,
+ "schema_version": 2,
"layers": [
- {
- "name": "prompt",
- "type": "plain.prompt",
- "config": {
- "prefix": "You are concise.",
- "user": "Summarize the current state."
- }
- }
+ {"name": "prompt", "config": {"prefix": "You are concise.", "user": "Summarize the current state."}},
+ {"name": "execution_context", "config": {"tenant_id": "tenant-id", "agent_mode": "agent_app", "invoke_from": "web-app"}},
+ {"name": "llm", "config": {"plugin_id": "langgenius/openai", "model_provider": "openai", "model": "gpt-4o-mini"}}
]
}
}
```
`config.user` can be a string or a list of strings. Empty or whitespace-only
-effective prompts are rejected during create-run validation before the run is
-persisted or scheduled.
+effective prompts and module configuration are validated by the runner before
+resource acquisition or model I/O. HTTP create-run parses the wire shape, persists
+the run and schedules execution; configuration errors produce `run_failed`.
-Agent App callers can use the `dify.user_prompt` layer to send text and images
+Agent App callers can use the `agent_app_user_prompt` module to send text and images
in the same model turn. Each image must provide exactly one transport: an
HTTP(S) `url` or unprefixed Base64 data in `base64_data`. The image is passed as
structured multimodal content; it is not interpolated into `config.text`.
@@ -421,7 +419,6 @@ structured multimodal content; it is not interpolated into `config.text`.
```json
{
"name": "agent_app_user_prompt",
- "type": "dify.user_prompt",
"config": {
"text": "Describe this image.",
"files": [
@@ -451,17 +448,23 @@ is presented, independently of its file `type` (`image`, `document`, `audio`,
`transfer_method: "remote_url"` with `url`, or a `local_file`, `tool_file`, or
`datasource_file` transfer method with a canonical `reference`.
-The layer appends sandbox file-download instructions for download attachments
+The module appends sandbox file-download instructions for download attachments
and adds multimodal attachments as structured model content. Callers keep
`config.text` as the original user text. Omitting `config.files` is equivalent
to an empty list.
-The optional Pydantic AI history layer uses the reserved name `history` and
-persists captured messages in session snapshots for later resume. Resume from a
-terminal event's `session_snapshot` using the same layer composition, names, and
-order. Success always contains a snapshot. Failure and cancellation contain one
-only when compositor entry succeeded and layer exit completed; otherwise callers
-should retain their previous snapshot.
+The optional history module uses the reserved name `history`. It persists captured
+messages, including failure and cancellation history, with current instructions
+removed. Snapshots have `schema_version: 2` and a `layers` JSON dict containing only
+State. Submit current Config on each turn along with the previous snapshot. Modules
+can be added or removed between turns; retained state is matched by name.
+
+Known v1 snapshots are converted once at read time without restoring legacy
+instances or lifecycle. Native resource scopes always release leases and clear
+tracked shell jobs at run exit. Success always contains the resulting snapshot;
+failure and cancellation contain one when validated run data was available and
+cleanup produced a snapshot. Callers retain the previous snapshot when none is
+returned. Product Workspace retirement remains owned by the API.
## Observing runs
@@ -493,12 +496,10 @@ end with `run_cancelled`. Each run can append at most one of these terminal
events. Event envelopes retain `id`, `run_id`, `type`, `data`, and `created_at`;
`data` is typed per event type,
including Pydantic AI's `AgentStreamEvent` payload for `pydantic_ai_event` and a
-terminal event may contain a `CompositorSessionSnapshot` for resumption.
+terminal event may contain a `SessionSnapshot` for resumption.
`run_succeeded` always contains it; `run_failed` and `run_cancelled` contain it
-only when compositor entry succeeded, layer exit completed, and a post-exit
-snapshot was actually produced. A successful run has exactly one active result branch: JSON-safe
-`output` for final answers, or `deferred_tool_call` when a layer such as
-`dify.ask_human` ends the current agent run with an external deferred tool call.
+when the runner produced State after native capability cleanup. A successful run
+contains JSON-safe `output`, which may be null.
Failed event payloads contain the diagnostic `error`, optional source-specific
`reason`, optional stable `error_type`, and optional `session_snapshot`.
Cancelled payloads likewise may contain `session_snapshot`. Pydantic AI request/step budget
@@ -520,5 +521,5 @@ The repository includes simple consumers that print observed output/events:
- `dify-agent/examples/dify_agent/dify_agent_examples/run_server_sse_consumer.py`
consumes raw SSE frames for an existing run id.
-The create-run examples submit Dify plugin model layers, so they require Redis,
+The create-run examples submit Dify plugin model modules, so they require Redis,
the Agent server, Dify API gateway settings, and a configured model provider in Dify.
diff --git a/dify-agent/docs/dify-agent/index.md b/dify-agent/docs/dify-agent/index.md
index 2683fa78bd8..9e21843877d 100644
--- a/dify-agent/docs/dify-agent/index.md
+++ b/dify-agent/docs/dify-agent/index.md
@@ -1,7 +1,39 @@
# Dify Agent runtime
-Dify Agent hosts Agenton-composed Pydantic AI runs behind a FastAPI API. Its
-source code stays under `src/dify_agent`, while framework-neutral Agenton code
-stays under `src/agenton` and `src/agenton_collections`.
+Dify Agent hosts native Pydantic AI runs behind FastAPI. Implementations remain
+under `src/dify_agent`; there is no separate agent composition framework.
-See the [operations guide](guide/index.md) for local server behavior.
+Each module declares Pydantic `Config`, `State`, and exactly one native
+`Capability` or `Toolset`. The server registry maps a name to a module. Names
+identify configuration, state and instances; aliases can use the same module
+with independent state. New instances are created for every run.
+
+`ctx.deps.layers[name]` contains JSON `config` and `state`. Config is read-only
+within a run and comes from the current request. State belongs to its module;
+validated models are copies, so mutations require explicit
+`entry["state"] = state.model_dump(mode="json")` writeback. Stateful tools that
+read and modify across awaits execute sequentially.
+
+`deps.services` borrows lifespan clients and server settings. `deps.resources`
+holds only operation leases, shell sessions and temporary credentials. The
+capability that acquires a resource releases it in `wrap_run` using `finally`,
+including failures and cancellation. The API owns durable Binding/Workspace
+retirement and saves snapshots in the owning session.
+
+Registered production names are `agent_soul_prompt`, `workflow_node_job_prompt`,
+`workflow_user_prompt`, `agent_app_user_prompt`, `execution_context`, `runtime`,
+`shell`, `config`, `history`, `llm`, `tools`, `core_tools`, `knowledge`, `output`,
+plus `prompt` and `user_prompt` convenience names. HTTP input cannot supply an
+import path. Cross-module references live in Config, for example
+`execution_context`, `runtime`, and `shell`; the loader validates their targets
+before I/O. Instruction ordering is unspecified. Native capability ordering
+preserves Runtime → Shell → Config resource scopes.
+
+Model, output type, current user content and initial history use explicit runner
+assembly and native Agent arguments. Knowledge eager results stay in the user
+role through a native model-request hook. Tool dispatch, instructions and
+capability hooks use native Pydantic AI interfaces.
+
+See [run lifecycle](concepts/run-lifecycle/index.md),
+[resources](concepts/runtime-resources/index.md), and the
+[operations guide](guide/index.md).
diff --git a/dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md b/dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md
deleted file mode 100644
index fc00b58aef5..00000000000
--- a/dify-agent/docs/dify-agent/user-manual/ask-human-layer/index.md
+++ /dev/null
@@ -1,287 +0,0 @@
-# Ask human layer
-
-The ask human layer exposes one model-visible tool that lets an agent end the
-current run with a structured request for human input. This page is for Dify
-Agent clients that build `CreateRunRequest` payloads and then interpret terminal
-run events.
-
-The layer type id is `dify.ask_human`. It does not deliver forms, choose
-recipients, enforce authorization, or wait inside the agent run. It only gives
-the model a safe way to ask for human input and returns that request as a
-deferred tool call.
-
-## Layer contract
-
-| Property | Value |
-| --- | --- |
-| Type id | `dify.ask_human` |
-| Common layer name | `ask_human` |
-| Config DTO | `DifyAskHumanLayerConfig` |
-| Model-visible tool | `ask_human` by default, configurable with `tool_name` |
-| Tool kind | pydantic-ai `external` deferred tool |
-| Terminal event | `run_succeeded` |
-| Terminal payload branch | `run_succeeded.data.deferred_tool_call` |
-
-The agent run does not enter a paused status. When the model calls the ask-human
-tool, the current run succeeds with a `deferred_tool_call` instead of normal
-`output`. The client is responsible for turning that deferred call into its own
-human-facing workflow, collecting a result, and starting another run with
-`deferred_tool_results`.
-
-## Basic usage
-
-Add the ask human layer to the same composition as the prompt, history, LLM, and
-optional structured-output layers:
-
-```python {test="skip" lint="skip"}
-from agenton_collections.layers.plain import PromptLayerConfig
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
-from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig
-from dify_agent.layers.execution_context import (
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- DifyExecutionContextLayerConfig,
-)
-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID
-from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec
-
-
-request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(
- prefix="You can ask a human only when the missing decision is required to continue.",
- user="Review the deployment plan and proceed only after getting the required approval.",
- ),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="replace-with-tenant-id",
- user_id="replace-with-user-id",
- user_from="account",
- app_id="replace-with-app-id",
- agent_mode="single_step",
- invoke_from="debugger",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_HISTORY_LAYER_ID,
- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- ),
- RunLayerSpec(
- name="ask_human",
- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
- config=DifyAskHumanLayerConfig(
- max_fields=4,
- max_actions=2,
- allowed_field_types=["paragraph", "select"],
- allow_file_fields=False,
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="gpt-5.2",
- ),
- ),
- ]
- )
-)
-```
-
-Include a [history layer](../history-layer/index.md) whenever you expect to
-resume after a human answer. The pending tool call is stored in pydantic-ai
-message history, so the resumed run needs both the returned `session_snapshot`
-and the same logical composition with the history layer still present.
-
-## Config fields
-
-`DifyAskHumanLayerConfig` controls the model-facing tool identity and guardrails.
-It intentionally does not contain delivery settings.
-
-| Field | Type | Default | Meaning |
-| --- | --- | --- | --- |
-| `enabled` | `bool` | `True` | When false, the layer exposes neither the tool nor the prompt guidance. |
-| `tool_name` | `str` | `"ask_human"` | Model-visible tool name. Must be a valid identifier. |
-| `tool_description` | `str \| None` | default description | Optional model-visible tool description. |
-| `max_fields` | `int` | `8` | Maximum number of fields the model may request. Use `0` for action-only requests. |
-| `max_actions` | `int` | `4` | Maximum number of human actions the model may request. |
-| `allowed_field_types` | `list["paragraph" \| "select" \| "file" \| "file-list"]` | `["paragraph", "select"]` | Field types accepted by runtime validation. |
-| `allow_file_fields` | `bool` | `False` | File field types are rejected unless this is true and the type is listed in `allowed_field_types`. |
-| `max_markdown_chars` | `int` | `8000` | Maximum length for the optional `markdown` body. |
-| `max_question_chars` | `int` | `1000` | Maximum length for the required `question`. |
-| `max_field_label_chars` | `int` | `120` | Maximum label length for each field. |
-| `max_action_label_chars` | `int` | `80` | Maximum label length for each action. |
-
-Configured limits are also capped by server hard limits. If a config exceeds a
-hard cap, request validation fails before the run can execute.
-
-The layer converts these limits into a prompt hint automatically. Clients do not
-need to write a separate system prompt listing the limits, although they may add
-business-specific guidance such as when human input is appropriate.
-
-## What the model can request
-
-When enabled, the layer exposes an external deferred tool whose argument shape is
-`AskHumanToolArgs`:
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `title` | `str \| None` | Optional short title for the human request. |
-| `question` | `str` | Required question/instruction for the human. |
-| `markdown` | `str \| None` | Optional longer Markdown body. Treat it as untrusted user-visible content. |
-| `fields` | `list[AskHumanField]` | Optional structured fields for the human to fill. |
-| `actions` | `list[AskHumanAction]` | Optional action buttons. If omitted, Dify Agent normalizes to a single primary `Submit` action. |
-| `urgency` | `"normal" \| "high"` | Hint for downstream systems; it is not a delivery policy. |
-
-Supported field variants:
-
-- `paragraph`: free-text input.
-- `select`: single-choice input with unique option values.
-- `file`: single-file input, only when file fields are allowed.
-- `file-list`: multi-file input, only when file fields are allowed.
-
-Tool arguments are validated again after the model calls the tool. Invalid calls
-produce a model retry before a terminal success is emitted.
-
-## Handling a deferred human request
-
-Stream or poll run events as usual. A successful final answer has
-`event.data.output`. A successful human request has `event.data.deferred_tool_call`.
-Exactly one branch is set.
-
-```python {test="skip" lint="skip"}
-deferred_call = None
-snapshot = None
-
-async for event in client.stream_events(run_id):
- if event.type != "run_succeeded":
- continue
- snapshot = event.data.session_snapshot
- if event.data.deferred_tool_call is not None:
- deferred_call = event.data.deferred_tool_call
- else:
- final_output = event.data.output
- break
-
-if deferred_call is not None:
- # Render your own human-facing form, enqueue notification, pause an outer
- # workflow, or store the request for later. Dify Agent does not do that part.
- print(deferred_call.tool_call_id, deferred_call.args)
-```
-
-A typical deferred payload looks like this:
-
-```json
-{
- "tool_call_id": "call_01H...",
- "tool_name": "ask_human",
- "args": {
- "title": "Deployment approval",
- "question": "Can we deploy version 2026.06.10 to production now?",
- "fields": [
- {
- "type": "paragraph",
- "name": "comment",
- "label": "Approval comment",
- "required": false
- }
- ],
- "actions": [
- {"id": "approve", "label": "Approve", "style": "primary"},
- {"id": "reject", "label": "Reject", "style": "destructive"}
- ],
- "urgency": "normal"
- },
- "metadata": {
- "layer_type": "dify.ask_human",
- "tool_name": "ask_human",
- "schema_version": 1
- }
-}
-```
-
-The `args` object is model-generated content. Validate and sanitize it before
-rendering it to end users.
-
-## Resume with a human result
-
-After your client collects a human answer, create a new run with:
-
-- the previous `session_snapshot`;
-- a matching composition that still includes the history and ask-human layers;
-- `deferred_tool_results.calls[tool_call_id]` containing the human result.
-
-```python {test="skip" lint="skip"}
-from dify_agent.layers.ask_human import AskHumanToolResult
-from dify_agent.protocol import DeferredToolResultsPayload
-
-
-human_result = AskHumanToolResult(
- status="submitted",
- action={"id": "approve", "label": "Approve"},
- values={"comment": "Approved for the planned window."},
- message="The human approved the deployment.",
-)
-
-resume_request = CreateRunRequest(
- composition=composition_with_same_layer_names_and_order,
- session_snapshot=snapshot,
- deferred_tool_results=DeferredToolResultsPayload(
- calls={deferred_call.tool_call_id: human_result.model_dump(mode="json")},
- ),
-)
-```
-
-Dify Agent passes the supplied result back to pydantic-ai as the return value of
-the original external tool call, then the model continues. The resumed run may
-produce a final `output`, or it may produce another `deferred_tool_call` if the
-agent needs another human turn.
-
-Timeouts and unavailable humans should also be sent as tool results instead of
-being treated as agent-run failures:
-
-```json
-{
- "status": "timeout",
- "action": {"id": "__timeout", "label": "Timeout"},
- "values": {},
- "message": "The human did not respond before the workflow timeout."
-}
-```
-
-## Client responsibilities
-
-The ask human layer deliberately leaves product decisions to the caller. Clients
-must decide how to:
-
-- persist the deferred call and correlate it with a human-facing task;
-- render and sanitize the requested fields/actions;
-- choose recipients, channels, and timeout policy;
-- authorize who may answer;
-- transform the human submission into `AskHumanToolResult`;
-- resume with the returned `session_snapshot` and matching composition.
-
-Do not put recipient emails, workspace member ids, public URLs, auth tokens, or
-timeout policy in the tool arguments. The model-facing request is untrusted and
-should not control delivery or authorization.
-
-## Troubleshooting
-
-| Symptom | What to check |
-| --- | --- |
-| Run fails with `Deferred tool results require a 'history' layer` | Add the `history` layer and resume with the prior snapshot. |
-| Run fails with `pending tool call can be resumed` | Keep the history layer active for the initial deferred run. |
-| Run fails with `exactly one deferred call` | The MVP supports one ask-human call per run. Ask the model to ask one question at a time. |
-| Run fails with `tool name must be ...` | Use the configured `tool_name`; do not rename it only in downstream form code. |
-| File fields are rejected | Set `allow_file_fields=True` and include `file` or `file-list` in `allowed_field_types`. |
-| `run_succeeded.data.output` is absent | Check `run_succeeded.data.deferred_tool_call`; this is a human-request success, not a failed run. |
diff --git a/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md b/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md
index 582d7fac155..c17b4626a19 100644
--- a/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/execution-context-layer/index.md
@@ -1,92 +1,7 @@
-# Execution context layer
+# Execution context module
-The execution-context layer carries shared Dify run identifiers plus the tenant
-and optional user context needed for plugin-daemon calls. Server settings still
-provide the plugin daemon URL and API key.
-
-Use it together with a [plugin LLM layer](../plugin-llm-layer/index.md) and,
-when the caller wants Dify tools exposed to the model, a
-[plugin tool layer](../plugin-tool-layer/index.md). Both business layers depend
-on this layer to reach the plugin daemon.
-
-## Config fields
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `tenant_id` | `str` | Dify tenant/workspace id used when calling the plugin daemon. |
-| `user_id` | `str \| None` | Optional end-user id passed through to the plugin daemon. |
-| `invoke_from` | `Literal[...]` | Dify caller category recorded for observability and correlation. |
-| `app_id` / `workflow_id` / `workflow_run_id` / `node_id` / `node_execution_id` / `conversation_id` / `agent_id` / `agent_config_version_id` / `trace_id` | `str \| None` | Optional Dify-owned execution identifiers forwarded with the run. |
-
-## Trajectory span attributes
-
-When Agent trajectory export is enabled, this layer's fields are attached to every
-trajectory span of the run. The names follow the Dify Enterprise Data Push
-dictionary so a trajectory span joins the platform's own workflow and node signals
-on the same keys. Fields you leave unset are omitted, so an Agent App turn carries
-`dify.conversation.id` while a workflow Agent node carries the workflow keys.
-
-| Config field | Span attribute |
-| --- | --- |
-| `tenant_id` | `dify.tenant_id` |
-| `app_id` | `dify.app_id` |
-| `agent_id` | `dify.agent_id` |
-| `user_id` | `gen_ai.user.id` |
-| `invoke_from` | `dify.invoke_from` |
-| `conversation_id` | `dify.conversation.id` |
-| `workflow_id` | `dify.workflow.id` |
-| `workflow_run_id` | `dify.workflow.run_id` |
-| `node_id` | `dify.node.id` |
-| `node_execution_id` | `dify.node.execution_id` |
-| `trace_id` | `dify.trace_id` |
-
-`app_id` is the app the run was invoked through, so a workflow Agent node reports
-the workflow's own app rather than the Agent's.
-
-The execution-context layer type id is `dify.execution_context`.
-
-## Basic usage
-
-```python {test="skip" lint="skip"}
-from dify_agent.layers.execution_context import (
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- DifyExecutionContextLayerConfig,
-)
-from dify_agent.protocol import RunLayerSpec
-
-
-execution_context_layer = RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="replace-with-tenant-id",
- user_id="replace-with-user-id",
- invoke_from="workflow_run",
- ),
-)
-```
-
-If you do not need a user id, omit `user_id` or pass `None`. Most optional
-execution identifiers may also be omitted when they are not available.
-
-## Server-side settings
-
-The execution-context layer config does not include daemon transport settings.
-Configure these on the Dify Agent server instead:
-
-```env
-DIFY_AGENT_PLUGIN_DAEMON_URL=http://localhost:5002
-DIFY_AGENT_PLUGIN_DAEMON_API_KEY=replace-with-plugin-daemon-server-key
-```
-
-This keeps server credentials out of client-submitted layer config and out of
-session snapshots.
-
-## Notes
-
-- The execution-context layer does not open, cache, close, or snapshot HTTP clients.
-- Concrete `plugin_id` values belong to the business layer that invokes the
- daemon: the plugin LLM layer for model calls and each plugin tool config for
- tool calls.
-- The conventional layer name is `execution_context`. If you use another name,
- point the LLM and tool layer dependencies at that name.
+`dify_agent.layers.execution_context.layer` declares Config, empty State and
+Capability. Config carries tenant/user/app/invoke identity and correlation IDs.
+Other modules refer to its registered name in their Config. Server-only daemon
+settings and clients are borrowed from Deps.services. Knowledge retrieval
+requires its complete caller identity before any external request.
diff --git a/dify-agent/docs/dify-agent/user-manual/history-layer/index.md b/dify-agent/docs/dify-agent/user-manual/history-layer/index.md
index 473035fda3e..1da5eea2088 100644
--- a/dify-agent/docs/dify-agent/user-manual/history-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/history-layer/index.md
@@ -1,140 +1,8 @@
-# History layer
-
-The history layer stores pydantic-ai conversation history in the Agenton session
-snapshot. Add it when a later run should resume the previous conversation.
-
-The history layer is state-only: it contributes no prompt text, user prompt, or
-tools, and it owns no live resources.
-
-## Layer contract
-
-| Property | Value |
-| --- | --- |
-| Reserved layer name | `history` |
-| Type id | `pydantic_ai.history` |
-| Config | none |
-| Dependencies | none |
-
-Use at most one history layer. It must be named `history` and must not declare
-dependencies.
-
-## Basic usage
-
-```python {test="skip" lint="skip"}
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, RunLayerSpec
-
-
-history_layer = RunLayerSpec(
- name=DIFY_AGENT_HISTORY_LAYER_ID,
- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
-)
-```
-
-Include this layer in the same composition as your prompt, plugin, and LLM
-layers.
-
-## Compaction and persistence
-
-When the LLM layer supplies `context_window_tokens`, Dify Agent sets the Harness
-target to `min(floor(window * 0.8), window - max_tokens)` for a positive
-`model_settings.max_tokens`; otherwise it uses `floor(window * 0.8)`. A target
-that is not positive rejects the run before model invocation.
-
-Harness estimates and, when needed, rewrites history immediately before model
-requests. It clears older tool results first, retaining the latest three
-tool-call/result pairs and their inputs. If the history is still over target, the
-same current model incrementally summarizes older messages while retaining the
-latest twenty messages and the first user message.
-
-With a history layer, once pydantic-ai binds and builds messages in the run
-capture, the captured, possibly rewritten history replaces the stored messages
-in the terminal session snapshot. This applies to successful, failed, and
-cancelled runs. A failure or cancellation before the capture contains any
-messages preserves the previously restored history. An interrupted capture can
-include a partial response or tool-return request marked `state="interrupted"`;
-pydantic-ai repairs that state when the snapshot is used by a later independent
-run. A run cancelled after the model returned tool calls but before any of them
-ran is also stored with that marker, so the calls it never executed do not block
-the next user prompt. Without this layer, compaction and interrupted messages affect only the
-current run.
-
-## Resume a conversation
-
-Successful runs return a terminal event with both final output and a resumable
-session snapshot. Failed and cancelled terminal events can also carry a session
-snapshot that checkpoints current history, but they do not change the interrupted
-run's terminal status into success.
-
-```python {test="skip" lint="skip"}
-accepted = await client.create_run(request)
-
-async for event in client.stream_events(accepted.run_id):
- if event.type == "run_succeeded":
- output = event.data.output
- snapshot = event.data.session_snapshot
- break
-```
-
-Pass `snapshot` to the next request and keep the same layer names and order:
-
-```python {test="skip" lint="skip"}
-next_request = CreateRunRequest(
- composition=composition_with_the_same_layer_names_and_order,
- session_snapshot=snapshot,
-)
-```
-
-`CreateRunRequest.on_exit` defaults to suspending layers, which makes the
-terminal snapshot resumable. Keep that default for normal memory flows.
-
-## What gets stored
-
-Dify Agent handles memory conservatively:
-
-1. Current system prompts are passed as run-level pydantic-ai instructions.
-2. Stored history is sent to the model before the current user prompt.
-3. When the LLM layer includes `context_window_tokens`, Harness may rewrite
- over-target history immediately before a model request as described above.
-4. Once pydantic-ai binds and builds messages in the run capture, the complete
- captured and possibly compacted history is written back to the layer on
- success, failure, timeout, or cancellation.
-5. If failure or cancellation occurs before the capture contains any messages,
- the previously restored history remains unchanged.
-6. Run-level system instructions are removed before history is persisted.
-7. Interrupted partial messages retain pydantic-ai's `state="interrupted"` marker
- so a later independent run can repair and continue from the checkpoint. A
- trailing response whose tool calls the interrupted run never executed is
- stored with the same marker; a run that ends in a deferred tool request keeps
- its open call so the next run can answer it.
-8. Failed and cancelled runs keep their terminal status; their snapshot is a
- checkpoint, not a successful continuation of the interrupted run.
-
-## Persist snapshots outside the client process
-
-Session snapshots are Pydantic models and can be saved as JSON:
-
-```python {test="skip" lint="skip"}
-from pathlib import Path
-
-from agenton.compositor import CompositorSessionSnapshot
-
-
-snapshot_path = Path("session_snapshot.json")
-snapshot_path.write_text(snapshot.model_dump_json(), encoding="utf-8")
-
-restored_snapshot = CompositorSessionSnapshot.model_validate_json(
- snapshot_path.read_text(encoding="utf-8")
-)
-```
-
-Always restore snapshots with the same layer names and order that produced them.
-
-## Troubleshooting
-
-| Symptom | What to check |
-| --- | --- |
-| `must use reserved layer name 'history'` | Rename the layer to `history`. |
-| `does not support dependencies` | Remove `deps` from the history layer. |
-| Resume fails with snapshot lifecycle errors | Use a terminal snapshot whose layers were suspended, and keep layer names/order unchanged. |
-| System prompts appear missing from saved memory | This is expected; current system prompts are temporary and are not persisted. |
+# History module
+
+`dify_agent.layers.history` declares Config, State and Capability. Config is
+empty. State contains `messages`, encoded as JSON using Pydantic AI message
+schemas. The runner explicitly loads initial message_history and writes the
+captured history on every terminal outcome, preserving compaction and partial
+responses. Current instructions are removed and unmatched trailing calls are
+marked interrupted on failure or cancellation. The reserved name is `history`.
diff --git a/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md b/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md
index 8b8c970e9e8..8c98f71abd8 100644
--- a/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/plugin-llm-layer/index.md
@@ -1,142 +1,7 @@
-# Plugin LLM layer
+# Model module
-The plugin LLM layer selects the plugin package, model provider, model name,
-and optional model settings for the current run. Dify Agent reads the model
-from the reserved layer name `llm`; Dify API resolves model credentials.
-
-It must depend on an [execution context layer](../execution-context-layer/index.md),
-because that layer supplies the caller identity required by the API gateway.
-
-## Config fields
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `plugin_id` | `str` | Plugin package id, for example `langgenius/openai`. |
-| `model_provider` | `str` | Provider name inside `plugin_id`. Use the value of `DIFY_AGENT_PROVIDER` from `dify-agent/.env`. |
-| `model` | `str` | Model name. Use the value of `DIFY_AGENT_MODEL_NAME` from `dify-agent/.env`. |
-| `model_settings` | `ModelSettings \| None` | Optional pydantic-ai model settings. |
-| `context_window_tokens` | `int \| None` | Positive effective context-window capability metadata. Enables window-based compaction when present; omission disables it. |
-
-The plugin LLM layer type id is `dify.plugin.llm`.
-
-## Basic usage
-
-```python {test="skip" lint="skip"}
-from dify_agent.layers.dify_plugin import DIFY_PLUGIN_LLM_LAYER_TYPE_ID, DifyPluginLLMLayerConfig
-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, RunLayerSpec
-
-
-MODEL_PROVIDER = "replace-with-provider-from-dify-agent-env"
-MODEL_NAME = "replace-with-model-from-dify-agent-env"
-PLUGIN_ID = "langgenius/openai"
-
-llm_layer = RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id=PLUGIN_ID,
- model_provider=MODEL_PROVIDER,
- model=MODEL_NAME,
- ),
-)
-```
-
-`deps={"execution_context": "execution_context"}` means: bind the LLM layer's
-dependency field named `execution_context` to the composition layer named
-`execution_context`.
-
-Set `MODEL_PROVIDER` and `MODEL_NAME` to the same values as
-`DIFY_AGENT_PROVIDER` and `DIFY_AGENT_MODEL_NAME` in `dify-agent/.env`.
-
-## Context compaction
-
-Dify product request builders resolve `context_window_tokens` from the selected
-model plugin schema using the current tenant and user credentials. A client that
-constructs `DifyPluginLLMLayerConfig` directly is responsible for supplying an
-accurate positive value. The field is model capability metadata: Dify Agent does
-not forward it as a Provider parameter or merge it into `model_settings`.
-
-For a known window, Dify Agent computes the Harness compaction target as:
-
-```text
-min(floor(context_window_tokens * 0.8), context_window_tokens - max_tokens)
-```
-
-The second term applies only when `model_settings.max_tokens` is positive. A
-non-positive target rejects the run before model invocation. Immediately before
-model requests, Harness estimates the message history and rewrites it when it is
-over target: it first clears old tool results while retaining the three most
-recent tool-call/result pairs and their inputs; if still over target, the current
-model incrementally summarizes older history while retaining the latest twenty
-messages and the first user message.
-
-Compaction affects later runs only when the composition has a
-[history layer](../history-layer/index.md). Once pydantic-ai binds and builds
-messages in the run capture, successful, failed, timed-out, and cancelled runs
-write the captured rewritten history into their terminal session snapshot. A
-failure or cancellation before the capture contains any messages preserves the
-previously restored history. Interrupted partial messages may be included and
-repaired when that checkpoint is used by a later independent run; the interrupted
-run's terminal status remains unchanged.
-
-## Complete minimal model composition
-
-Most runs include a prompt, execution-context layer, and LLM layer:
-
-```python {test="skip" lint="skip"}
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DifyPluginLLMLayerConfig,
-)
-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, RunComposition, RunLayerSpec
-
-
-MODEL_PROVIDER = "replace-with-provider-from-dify-agent-env"
-MODEL_NAME = "replace-with-model-from-dify-agent-env"
-PLUGIN_ID = "langgenius/openai"
-
-composition = RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- config=PromptLayerConfig(prefix="You are concise.", user="Say hello."),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="replace-with-tenant-id",
- user_id="replace-with-user-id",
- user_from="account",
- app_id="replace-with-app-id",
- agent_mode="single_step",
- invoke_from="debugger",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id=PLUGIN_ID,
- model_provider=MODEL_PROVIDER,
- model=MODEL_NAME,
- ),
- ),
- ]
-)
-```
-
-## Notes
-
-- The model layer must use the reserved name `llm` (`DIFY_AGENT_MODEL_LAYER_ID`).
-- `plugin_id` belongs here because model calls are plugin-specific business
- calls. The shared execution-context layer carries the Dify caller context.
-- Model credentials are never accepted from the Agent request. Dify API resolves
- the tenant's current provider configuration and owns quota accounting.
-- Omitting `context_window_tokens` disables window-based compaction. It does not
- limit or otherwise change the Provider's own context-window enforcement.
+`dify_agent.layers.dify_plugin.llm_layer` declares Config, State and Capability.
+The reserved `llm` name selects model assembly. Public Config contains plugin,
+provider, model, model settings, context window and an `execution_context` name.
+The runtime builds a model through the Dify API metered gateway with borrowed
+lifespan HTTP services. Credentials stay API-owned; no model/client is persisted.
diff --git a/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md b/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md
index a7618462c92..ecd604a6619 100644
--- a/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/plugin-tool-layer/index.md
@@ -1,130 +1,9 @@
-# Plugin tool layer
-
-The plugin tool layer exposes Dify plugin tools to the model. It is designed for
-Dify API to build after it has resolved a user's tool selections, plugin daemon
-declarations, credentials, and manual/runtime inputs.
-
-Unlike the plugin LLM layer, this layer may contain tools from multiple plugin
-packages. Each tool config carries its own `plugin_id`, while the shared
-[execution context layer](../execution-context-layer/index.md) still carries
-only tenant/user daemon context.
-
-## Responsibilities
-
-Dify API prepares the tool config before submitting the run request:
-
-- resolve the selected provider and tool name;
-- merge declared parameters with runtime parameters;
-- produce the model-visible JSON schema;
-- provide hidden/manual `runtime_parameters` and credentials;
-- choose the daemon `credential_type` for invocation.
-
-Dify Agent consumes that prepared config. At run time it validates required
-hidden inputs, applies defaults, casts invocation values, calls plugin daemon,
-and turns tool responses into model observations.
-
-## Config fields
-
-The plugin tools layer type id is `dify.plugin.tools`.
-
-`DifyPluginToolsLayerConfig` contains a list of `DifyPluginToolConfig` objects:
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `tools` | `list[DifyPluginToolConfig]` | Prepared plugin tools to expose to the model. |
-
-Each tool config has these fields:
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `plugin_id` | `str` | Plugin package id for this tool, for example `langgenius/wikipedia`. |
-| `provider` | `str` | Tool provider name inside the plugin. |
-| `tool_name` | `str` | Daemon tool name to invoke. |
-| `credential_type` | `"api-key" \| "oauth2" \| "unauthorized"` | Credential mode sent to plugin daemon. |
-| `name` | `str \| None` | Optional model-visible tool name. Defaults to `tool_name`. |
-| `description` | `str \| None` | Optional model-visible description. Defaults to the tool name. |
-| `credentials` | `dict[str, str \| int \| float \| bool \| None]` | Provider-specific tool credentials. |
-| `runtime_parameters` | `dict[str, JsonValue]` | Hidden/manual values merged into daemon invocation but omitted from the model schema. |
-| `parameters` | `list[DifyPluginToolParameter]` | API-prepared effective parameter declarations used for validation, defaults, and casting. |
-| `parameters_json_schema` | `dict[str, JsonValue]` | API-prepared JSON schema shown to the model. |
-
-## Example: Dify API prepared Wikipedia tool
-
-```python {test="skip" lint="skip"}
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- DifyPluginToolConfig,
- DifyPluginToolParameter,
- DifyPluginToolsLayerConfig,
-)
-from dify_agent.protocol import RunComposition, RunLayerSpec
-
-
-# Dify API side: resolve the selected tool into the API-side Tool runtime first,
-# for example with ToolManager.get_agent_tool_runtime(...). Then adapt its
-# effective ToolParameter objects at the protocol boundary. Dify Agent accepts
-# both ToolParameter attribute objects and ToolParameter.model_dump(mode="json")
-# dictionaries, ignoring API-only fields such as label and human_description.
-tool_runtime = ToolManager.get_agent_tool_runtime(...)
-effective_parameters = tool_runtime.get_merged_runtime_parameters()
-prepared_parameters = [
- DifyPluginToolParameter.model_validate(parameter)
- # If the API serializes first, use:
- # DifyPluginToolParameter.model_validate(parameter.model_dump(mode="json"))
- for parameter in effective_parameters
-]
-parameters_json_schema = tool_runtime.get_llm_parameters_json_schema()
-
-composition = RunComposition(
- layers=[
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="replace-with-tenant-id",
- user_id="replace-with-user-id",
- invoke_from="workflow_run",
- ),
- ),
- RunLayerSpec(
- name="tools",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/wikipedia",
- provider="wikipedia",
- tool_name="wikipedia_search",
- credential_type="unauthorized",
- name="wikipedia_search",
- description="Search Wikipedia for relevant pages.",
- parameters=prepared_parameters,
- runtime_parameters={"language": "en"},
- parameters_json_schema=parameters_json_schema,
- )
- ]
- ),
- ),
- ]
-)
-```
-
-`deps={"execution_context": "execution_context"}` means: bind the tool layer's
-dependency field named `execution_context` to the composition layer named
-`execution_context`.
-
-## Notes for Dify API callers
-
-- Do not ask Dify Agent to discover tool declarations. Resolve and prepare them
- in API before creating the run.
-- `parameters` should include all effective parameters, including hidden/manual
- ones needed for validation and default application.
-- `parameters_json_schema` should include only model-visible parameters. Omit
- hidden/manual parameters and file/system-file parameters unless they are truly
- intended for model input.
-- `runtime_parameters` should contain hidden/manual values selected by the user
- or derived from workflow variables.
-- Put each tool's `plugin_id` on the tool config. The shared execution-context
- layer has no package-specific identity.
+# Plugin tool module
+
+`dify_agent.layers.dify_plugin.tools_layer` declares Config, State and native
+Toolset. The `tools` registry name accepts API-prepared declarations, parameters,
+runtime values and model-facing schema, plus `execution_context` and optional
+`shell` Config references. Hidden/default parameter merging, loose schemas and
+observation mapping preserve the API-prepared contract. Sandbox paths use the
+referenced live shell session to upload files; file mappings resolve signed URLs
+through the borrowed Dify API client. Config and credentials are never snapshotted.
diff --git a/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md b/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md
index f31b2e41fca..c34c4d46925 100644
--- a/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/prompt-layer/index.md
@@ -1,71 +1,7 @@
-# Prompt layer
+# Prompt module
-The prompt layer provides the current run's system and user prompt fragments. In
-Dify Agent request bodies it is a regular `RunLayerSpec` with type id
-`plain.prompt`.
-
-Use it for:
-
-- system instructions that should be sent on this run
-- the current user input
-- optional suffix system instructions
-
-## Config fields
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `prefix` | `str` or `list[str]` | System prompt fragments collected before other prompt content. |
-| `user` | `str` or `list[str]` | Current user-message fragments for the run. |
-| `suffix` | `str` or `list[str]` | System prompt fragments collected after prefix content. |
-
-All fields default to an empty list. Dify Agent rejects a create-run request when
-the effective user prompt is empty or whitespace-only.
-
-## Basic usage
-
-```python {test="skip" lint="skip"}
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
-from dify_agent.protocol import RunLayerSpec
-
-
-prompt_layer = RunLayerSpec(
- name="prompt",
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- config=PromptLayerConfig(
- prefix="You are a concise assistant.",
- user="Summarize the incident in one paragraph.",
- ),
-)
-```
-
-## Multiple prompt fragments
-
-Use lists when the caller wants to keep fragments separate while still sending one
-run:
-
-```python {test="skip" lint="skip"}
-prompt_layer = RunLayerSpec(
- name="prompt",
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- config=PromptLayerConfig(
- prefix=[
- "You are an incident response assistant.",
- "Prefer concrete mitigation steps.",
- ],
- user=[
- "Database latency is elevated.",
- "Return the likely severity and next actions.",
- ],
- suffix="Do not invent metrics that are not provided.",
- ),
-)
-```
-
-## Notes
-
-- The run API does not accept a top-level `user_prompt`; submit user input through
- a prompt layer.
-- Prompt layer names are not reserved by the runtime, but `prompt` is the
- recommended conventional name.
-- When a [history layer](../history-layer/index.md) is present, current system
- prompts are passed as run-level instructions and are not saved into memory.
+`dify_agent.layers.prompt` declares Config, State and native Toolset. Config
+accepts `prefix`, `suffix` and `user` string fragments or lists. Prefix/suffix
+become dynamic instructions; `user` contributes current user content. State is
+empty. Instruction order is unspecified. Product names `agent_soul_prompt`,
+`workflow_node_job_prompt`, and `workflow_user_prompt` map to this module.
diff --git a/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md b/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md
index d6c5011637e..170d6be5220 100644
--- a/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/shell-layer/index.md
@@ -1,282 +1,14 @@
-# Shell layer
-
-The `dify.shell` layer exposes shellctl-backed commands to an Agent.
-It does not select a backend or own persistent Home, Workspace, or Binding
-resources. It consumes the operation-scoped `RuntimeLease` opened by a sibling
-`dify.runtime` layer.
-
-## Public configuration
-
-```python
-from dify_agent.layers.shell import (
- DIFY_SHELL_LAYER_TYPE_ID,
- DifyShellEnvVarConfig,
- DifyShellLayerConfig,
-)
-from dify_agent.protocol import RunLayerSpec
-
-RunLayerSpec(
- name="shell",
- type=DIFY_SHELL_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context", "runtime": "runtime"},
- config=DifyShellLayerConfig(
- env=[DifyShellEnvVarConfig(name="REPORT_FORMAT", value="markdown")],
- redact_patterns=["private-[A-Za-z0-9]+"],
- ),
-)
-```
-
-| Config field | Meaning |
-| --- | --- |
-| `cli_tools` | CLI bootstrap declarations with install commands and scoped environment metadata. |
-| `env` | Normal environment variables exported to Shell commands. |
-| `secret_refs` | Names of secret environment variables supplied by the backend environment. |
-| `redact_patterns` | Request-level regex patterns removed from Shell output shown to the model. |
-
-Endpoints, credentials, Home/Workspace paths, resource refs, timeouts, and
-network policy are not Shell config. Backend selection is server-private, and
-the opaque Binding ref belongs to `DifyRuntimeLayerConfig`.
-
-## Runtime requirements
-
-The server constructs one coherent runtime backend profile. Local, E2B, and
-OpenShell implement Home Snapshot and Execution Binding operations. Enterprise
-implements default-Home Binding creation, acquisition, and coupled destruction,
-while immutable Home Snapshot operations fail fast; there is no compatibility
-fallback to the retired Sandbox protocol.
-
-```python
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
-from dify_agent.runtime_backend.profile import RuntimeBackendSettings, create_runtime_backend_profile
-
-runtime_backend_profile = create_runtime_backend_profile(
- RuntimeBackendSettings(
- runtime_backend="local",
- local_sandbox_endpoint="http://127.0.0.1:5004",
- local_sandbox_auth_token="replace-with-shellctl-token",
- )
-)
-
-layer_providers = create_default_layer_providers(
- plugin_daemon_url="http://localhost:5002",
- plugin_daemon_api_key="replace-with-plugin-daemon-key",
- runtime_backend_profile=runtime_backend_profile,
-)
-```
-
-Equivalent standalone environment settings are:
-
-```env
-DIFY_AGENT_RUNTIME_BACKEND=local
-DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT=http://127.0.0.1:5004
-DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN=replace-with-shellctl-token
-# Optional when shellctl runs directly on a host without /home/dify:
-# DIFY_AGENT_LOCAL_SANDBOX_MATERIALIZED_HOME_ROOT=/tmp/dify-agent/materialized-homes
-# DIFY_AGENT_LOCAL_SANDBOX_WORKSPACE_ROOT=/tmp/dify-agent/workspaces
-# DIFY_AGENT_LOCAL_SANDBOX_HOME_SNAPSHOT_ROOT=/tmp/dify-agent/home-snapshots
-```
-
-The auth token may be empty when shellctl authentication is disabled. Dify-created
-E2B Sandboxes disable public traffic at creation and access shellctl through the
-E2B port proxy with its `traffic_access_token`. Acquiring a RuntimeLease fails if
-E2B does not provide a non-empty token. This policy applies only to newly created
-Sandboxes and does not retrofit existing ones.
-
-To let shell jobs call the Agent Stub with `dify-agent ...`, configure a
-Sandbox-reachable Agent Stub URL and a unique production secret. Remote
-deployments normally use a public Agent ingress. Local Compose uses
-`http://agent_backend:5050/agent-stub`, reached through the existing
-`agent_ssrf_proxy`; this configuration does not change the Compose network
-topology.
-
-```env
-DIFY_AGENT_STUB_API_BASE_URL=https://agent.example.com/agent-stub
-DIFY_AGENT_SANDBOX_FILES_BASE_URL=https://dify.example.com
-DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT=50
-DIFY_AGENT_SERVER_SECRET_KEY=replace-with-unpadded-base64url-for-32-random-bytes
-```
-
-HTTP URLs may be either the service root or the explicit `/agent-stub` root.
-The server normalizes a service root and rejects unrelated paths. The separate
-Sandbox file base must point to the Dify API ingress serving `/files/*`; it is
-used for CLI upload/download bytes, including Config file and skill pulls.
-`DIFY_AGENT_STUB_UPLOAD_FILE_SIZE_LIMIT` belongs to the Agent service, is in
-MiB, and defaults to `50`. The Agent service converts it to the signed upload
-URL's byte limit. Any ingress or proxy in front of `/files/*` must allow that
-file limit plus multipart framing and header overhead; its request-body limit
-does not need to be numerically identical.
-
-After `dify-agent file upload <path>` succeeds, the CLI prints JSON such as:
-
-```json
-{
- "transfer_method": "tool_file",
- "reference": "dify-file-ref:...",
- "public_download_url": "https://dify.example.com/files/tools/..."
-}
-```
-
-`reference` is the persistent canonical file identity and should be stored in
-structured output. `public_download_url` is a short-lived frontend presentation
-address: it is an absolute URL when Dify API `FILES_URL` has a public origin,
-or a same-origin `/files/...` relative URI when `FILES_URL` is empty. The CLI
-does not access this field. The former ambiguous `download_url` upload-output
-key is now named `public_download_url`.
-
-Server-side Binding downloads use
-`dify-agent file upload --no-download-link <path>`. This additive mode performs
-the same streaming ToolFile upload but skips the download-request step and
-prints only `transfer_method` plus the canonical `reference`. The regular
-`file upload` command keeps the link-producing behavior shown above.
-
-If the upload succeeds but creating the public URL fails, the command still
-prints the canonical mapping and exits with an error containing an exact
-`dify-agent file public-url <reference>` retry command. Run that command from a
-new shell tool call to create the public URL without uploading the file again.
-On success, `file public-url` prints the complete JSON mapping containing
-`transfer_method`, `reference`, and `public_download_url`.
-
-The Agent Stub authorization injected into a shell job is valid for five
-minutes. It does not refresh inside an already-running process. If a command
-reports that the authorization expired, start a new shell tool call and retry
-the command (or its reported `file public-url` recovery command).
-
-The injected JWE is masked as `***` in model-facing `shell_run`, `shell_wait`,
-and `shell_input` observations. Raw shellctl output and files referenced by
-`output_path` remain unchanged.
-
-## Request graph
-
-A shell-enabled run contains Execution Context, Runtime, and Shell layers:
-
-```mermaid
-flowchart LR
- EC["execution_context"] --> SH["shell"]
- RT["runtime<br/>backend_binding_ref"] --> SH
-```
-
-`DifyRuntimeLayer` acquires the Binding when the run's resource context opens
-and releases it when that operation exits. `DifyShellLayer` uses the active
-lease's commands, Home path, and Workspace path. It performs only
-best-effort cleanup of shell jobs; the persistent Binding lifecycle remains in
-Dify API.
-
-## Example request
-
-The Binding must already have been resolved or created by Dify API. Its backend
-ref is opaque to the request builder:
-
-```python {test="skip" lint="skip"}
-from agenton_collections.layers.plain import PromptLayerConfig
-from dify_agent.layers.dify_plugin.configs import DifyPluginLLMLayerConfig
-from dify_agent.layers.execution_context import (
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- DifyExecutionContextLayerConfig,
-)
-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
-from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID
-from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec
-
-
-request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(
- prefix="Use the workspace when local computation helps.",
- user="Create report.txt containing the current UTC timestamp, then summarize it.",
- ),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="92cca973-2d6f-45e0-906e-0b7eda5f2ccf",
- user_id="replace-with-user-id",
- user_from="account",
- app_id="replace-with-app-id",
- agent_id="8d542564-159d-4168-985c-dde8d8ff6092",
- agent_config_version_id="931a4cee-4434-4c1c-8fbd-0a3c7591095d",
- agent_config_version_kind="snapshot",
- agent_mode="workflow_run",
- invoke_from="debugger",
- ),
- ),
- RunLayerSpec(
- name="runtime",
- type=DIFY_RUNTIME_LAYER_TYPE_ID,
- config=DifyRuntimeLayerConfig(backend_binding_ref="opaque-backend-binding-ref"),
- ),
- RunLayerSpec(
- name="shell",
- type=DIFY_SHELL_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context", "runtime": "runtime"},
- config=DifyShellLayerConfig(),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/gemini",
- model_provider="google",
- model="gemini-2.5-flash",
- ),
- ),
- ]
- )
-)
-```
-
-The resource part serializes as:
-
-```json
-{
- "layers": [
- {
- "name": "runtime",
- "type": "dify.runtime",
- "config": {"backend_binding_ref": "opaque-backend-binding-ref"}
- },
- {
- "name": "shell",
- "type": "dify.shell",
- "deps": {"execution_context": "execution_context", "runtime": "runtime"},
- "config": {}
- }
- ]
-}
-```
-
-## Paths and persistence
-
-`RuntimeLease.layout.home_dir` and `workspace_dir` are absolute paths inside the
-backend execution namespace. They are not host filesystem paths and are not
-sent in the run request. Shell commands start in `workspace_dir`, while `HOME`
-is forced to `home_dir`; `~` therefore resolves to the current Binding's
-materialized Home. The runner also sets `TMPDIR`, `TMP`, and `TEMP` directly to
-`workspace_dir`, making the active Workspace both the default `cwd` and the
-temporary working space.
-
-Workspace content persists with the Workspace until Dify API retires and
-collects it. Releasing a RuntimeLease ends only the current operation. Dify API can later
-browse the Binding filesystem through Dify Agent's private
-`/execution-bindings/files/list`, `/execution-bindings/files/read`, and
-`/execution-bindings/files/download` routes, each of which acquires a fresh
-lease. Relative paths start in the Workspace, while `~` starts in the Binding's
-Home. Download uses the installed CLI to stream a ToolFile upload and returns
-only its canonical reference to Dify API.
-
-On Local, multiple Bindings may share a Workspace while each receives a
-separate materialized Home. Those directories may be siblings in one shellctl
-namespace; path isolation restricts a lease to its Home and Workspace. On E2B
-and OpenShell, one physical sandbox currently represents both Binding and
-Workspace, so shared Workspace attachment is unsupported.
-
-See [Runtime resources](../../concepts/runtime-resources/index.md) for the
-ledger and lifecycle contract. The [Operations Guide](../../guide/index.md)
-covers Local and E2B validation; the [OpenShell guide](../../guide/openshell.md)
-covers OpenShell configuration and validation.
+# Shell module
+
+`dify_agent.layers.shell.layer` declares Config, State and Capability. Config
+contains CLI tools, environment values, secret names, redaction patterns and
+`runtime` / optional `execution_context` references. Native ordering ensures an
+active lease exists before shell bootstrap and config eager pulls.
+
+The Capability exposes shell_run, shell_wait, shell_input and shell_interrupt
+through a native sequential Toolset. JSON State holds initialized, job_ids and
+job_offsets; live tokens remain in the run-scoped ShellSession. Bootstrap marks
+initialized only on success. Exit cleanup removes tracked jobs and clears IDs,
+offsets and credentials before Runtime releases the lease, including cancellation.
+The API owns Workspace/Binding retirement. HOME is reusable system space; cwd
+and TMPDIR/TMP/TEMP refer to the active Workspace.
diff --git a/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md b/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md
index 049351d1fd6..2b958d314f0 100644
--- a/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md
+++ b/dify-agent/docs/dify-agent/user-manual/structured-output-layer/index.md
@@ -1,101 +1,9 @@
-# Structured output layer
-
-The structured output layer makes the final answer follow a caller-provided JSON
-Schema. Add it when the client needs a JSON object instead of plain text.
-
-When present, Dify Agent exposes the schema to the model as a structured-output
-tool and validates the model response against the same schema.
-
-## Layer contract
-
-| Property | Value |
-| --- | --- |
-| Reserved layer name | `output` |
-| Type id | `dify.output` |
-| Config | `DifyOutputLayerConfig` |
-| Dependencies | none |
-
-Use at most one structured output layer. It must be named `output`.
-
-## Config fields
-
-| Field | Type | Meaning |
-| --- | --- | --- |
-| `json_schema` | `dict[str, JsonValue]` | Top-level object JSON Schema for the final answer. |
-| `description` | `str \| None` | Optional model-facing tool description. |
-| `strict` | `bool \| None` | Optional strictness flag passed to the output tool. |
-
-The structured-output tool name is fixed to `final_output`.
-
-## Basic usage
-
-```python {test="skip" lint="skip"}
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
-from dify_agent.protocol import DIFY_AGENT_OUTPUT_LAYER_ID, RunLayerSpec
-
-
-output_layer = RunLayerSpec(
- name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=DifyOutputLayerConfig(
- description="Structured incident summary returned by the agent.",
- strict=True,
- json_schema={
- "type": "object",
- "properties": {
- "title": {"type": "string"},
- "severity": {"type": "string", "enum": ["low", "medium", "high"]},
- "actions": {"type": "array", "items": {"type": "string"}},
- },
- "required": ["title", "severity", "actions"],
- "additionalProperties": False,
- },
- ),
-)
-```
-
-On success, the terminal event contains the validated JSON-safe object:
-
-```python {test="skip" lint="skip"}
-async for event in client.stream_events(run_id):
- if event.type == "run_succeeded":
- structured_output = event.data.output
-```
-
-If the `output` layer is omitted, Dify Agent keeps the default plain text output
-contract.
-
-## Schema limits
-
-The first structured-output version supports a practical subset of JSON Schema:
-
-- the top-level schema must be an object (`"type": "object"`)
-- the model-facing structured-output tool name is always `final_output`
-- remote `$ref` values are not supported
-- local refs are supported only under `#/$defs/...`
-- recursive `$defs` refs are not supported
-- `$ref` values inside ordinary literal keywords such as `const`, `enum`,
- `example`, and `examples` are treated as data, not schema refs
-
-## Validation and retry behavior
-
-The runtime builds a pydantic-ai output contract from the layer config. The same
-contract exposes the model-facing schema and validates the returned object.
-
-If the model returns an invalid object, pydantic-ai's normal output-validation
-retry behavior applies. If retries are exhausted, the run ends with `run_failed`.
-
-## Resuming runs with structured output
-
-Session snapshots store layer runtime state, not output-layer config. If you
-resume a run that uses structured output, include the same `output` layer again so
-the runtime can rebuild the output contract.
-
-## Troubleshooting
-
-| Symptom | What to check |
-| --- | --- |
-| `must use reserved layer name 'output'` | Rename the layer to `output`. |
-| Structured output falls back to text | Confirm the `output` layer is present and has type `dify.output`. |
-| Run fails before model resolution | Validate the JSON Schema and `$ref` usage. |
-| Resume loses structured output | Resubmit the same output layer; snapshots do not store the schema. |
+# Structured output module
+
+`dify_agent.layers.output.output_layer` declares Config, empty State and
+Capability. The reserved `output` name accepts a top-level object JSON Schema,
+optional description and strictness. The runner resolves native output_type
+before running the agent. A fresh dynamic type exposes the schema and performs
+JSON Schema validation in Pydantic AI's retry pipeline. The model-facing tool
+name is final_output. Local `#/$defs/` references are supported; remote or
+recursive references are rejected before I/O. Resume resubmits current Config.
diff --git a/dify-agent/docs/index.md b/dify-agent/docs/index.md
index 0fd13b6cb66..a38dc88ff2c 100644
--- a/dify-agent/docs/index.md
+++ b/dify-agent/docs/index.md
@@ -1,11 +1,5 @@
# Dify Agent
-This documentation is split by ownership boundary:
-
-- [Agenton](agenton/index.md) covers the framework-neutral layer compositor and reusable
- collection layers.
-- [Dify Agent](dify-agent/index.md) covers the Dify runtime, HTTP API, Redis-backed run
- storage, and server examples.
-
-The split mirrors the source tree so Agenton documentation and examples can be
-moved together if Agenton is published separately later.
+[Runtime modules](dify-agent/index.md) compose native Pydantic AI capabilities
+and toolsets. [Getting started](dify-agent/get-started/index.md) covers the HTTP
+protocol; [operations](dify-agent/guide/index.md) covers deployment.
diff --git a/dify-agent/examples/agenton/agenton_examples/__init__.py b/dify-agent/examples/agenton/agenton_examples/__init__.py
deleted file mode 100644
index 048f5b8e02e..00000000000
--- a/dify-agent/examples/agenton/agenton_examples/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-"""Runnable Agenton examples kept separate from Dify Agent runtime examples."""
diff --git a/dify-agent/examples/agenton/agenton_examples/__main__.py b/dify-agent/examples/agenton/agenton_examples/__main__.py
deleted file mode 100644
index d0794fc2f08..00000000000
--- a/dify-agent/examples/agenton/agenton_examples/__main__.py
+++ /dev/null
@@ -1,50 +0,0 @@
-"""Small CLI for listing or copying Agenton examples."""
-
-from __future__ import annotations
-
-import argparse
-import shutil
-import sys
-from pathlib import Path
-
-EXAMPLE_MODULES = (
- "basics",
- "pydantic_ai_bridge",
- "session_snapshot",
-)
-
-
-def cli() -> None:
- parser = argparse.ArgumentParser(
- prog="agenton_examples",
- description="List or copy Agenton examples.",
- )
- parser.add_argument("--copy-to", metavar="DEST", help="Copy example files to a new directory")
- args = parser.parse_args()
-
- examples_dir = Path(__file__).parent
- if args.copy_to:
- copy_to(examples_dir, Path(args.copy_to))
- return
-
- for module_name in EXAMPLE_MODULES:
- print(f"python -m agenton_examples.{module_name}")
-
-
-def copy_to(examples_dir: Path, destination: Path) -> None:
- if destination.exists():
- print(f'Error: destination path "{destination}" already exists', file=sys.stderr)
- sys.exit(1)
-
- destination.mkdir(parents=True)
- copied = 0
- for source in examples_dir.glob("*.py"):
- if source.name == "__init__.py":
- continue
- shutil.copy2(source, destination / source.name)
- copied += 1
- print(f'Copied {copied} Agenton example files to "{destination}"')
-
-
-if __name__ == "__main__":
- cli()
diff --git a/dify-agent/examples/agenton/agenton_examples/basics.py b/dify-agent/examples/agenton/agenton_examples/basics.py
deleted file mode 100644
index 81a3daeb18d..00000000000
--- a/dify-agent/examples/agenton/agenton_examples/basics.py
+++ /dev/null
@@ -1,142 +0,0 @@
-"""Run with: uv run --project dify-agent python -m agenton_examples.basics."""
-
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass, field
-from inspect import signature
-from typing import cast
-
-from typing_extensions import override
-
-from agenton.compositor import Compositor, LayerNode, LayerProvider
-from agenton.layers import LayerDeps, NoLayerDeps, PlainLayer, PlainToolType
-from agenton_collections.layers.plain import DynamicToolsLayer, ObjectLayer, PromptLayer, ToolsLayer, with_object
-from agenton_collections.layers.plain.basic import PromptLayerConfig
-
-
-@dataclass(frozen=True, slots=True)
-class AgentProfile:
- name: str
- audience: str
- tone: str
-
-
-class ProfilePromptDeps(LayerDeps):
- profile: ObjectLayer[AgentProfile] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass(slots=True)
-class ProfilePromptLayer(PlainLayer[ProfilePromptDeps]):
- @property
- @override
- def prefix_prompts(self) -> list[str]:
- profile = self.deps.profile.value
- return [
- f"You are {profile.name}, writing for {profile.audience}.",
- f"Keep the tone {profile.tone}.",
- ]
-
-
-@dataclass(slots=True)
-class TraceLayer(PlainLayer[NoLayerDeps]):
- events: list[str] = field(default_factory=list)
-
- @override
- async def on_context_create(self) -> None:
- self.events.append("create")
-
- @override
- async def on_context_suspend(self) -> None:
- self.events.append("suspend")
-
- @override
- async def on_context_resume(self) -> None:
- self.events.append("resume")
-
- @override
- async def on_context_delete(self) -> None:
- self.events.append("delete")
-
-
-def count_words(text: str) -> int:
- return len(text.split())
-
-
-@with_object(AgentProfile)
-def write_tagline(profile: AgentProfile, topic: str) -> str:
- return f"{profile.name}: {topic} for {profile.audience}, in a {profile.tone} voice."
-
-
-async def main() -> None:
- profile = AgentProfile(
- name="Agenton Assistant",
- audience="engineers composing agent capabilities",
- tone="precise and friendly",
- )
- trace_events: list[str] = []
- compositor = Compositor(
- [
- LayerNode("base_prompt", PromptLayer),
- LayerNode("extra_prompt", PromptLayer),
- LayerNode(
- "profile",
- LayerProvider.from_factory(
- layer_type=ObjectLayer,
- create=lambda _config: ObjectLayer[AgentProfile](profile),
- ),
- ),
- LayerNode("profile_prompt", ProfilePromptLayer, deps={"profile": "profile"}),
- LayerNode(
- "tools",
- LayerProvider.from_factory(
- layer_type=ToolsLayer,
- create=lambda _config: ToolsLayer(tool_entries=(count_words,)),
- ),
- ),
- LayerNode(
- "dynamic_tools",
- LayerProvider.from_factory(
- layer_type=DynamicToolsLayer,
- create=lambda _config: DynamicToolsLayer[AgentProfile](tool_entries=(write_tagline,)),
- ),
- deps={"object_layer": "profile"},
- ),
- LayerNode(
- "trace",
- LayerProvider.from_factory(layer_type=TraceLayer, create=lambda _config: TraceLayer(trace_events)),
- ),
- ]
- )
- configs = {
- "base_prompt": PromptLayerConfig(
- prefix="Use config dicts for serializable layers.",
- user="Explain how the composed agent should use its layers.",
- suffix="Before finalizing, make the result easy to scan.",
- ),
- "extra_prompt": PromptLayerConfig(prefix="Use constructed instances for objects, local code, and callables."),
- }
-
- async with compositor.enter(configs=configs) as run:
- print("Prompts:")
- for prompt in run.prompts:
- print(f"- {prompt.value}")
-
- print("\nUser prompts:")
- for prompt in run.user_prompts:
- print(f"- {prompt.value}")
-
- print("\nTools:")
- plain_tools = [cast(PlainToolType, tool) for tool in run.tools]
- for tool in plain_tools:
- print(f"- {tool.value.__name__}{signature(tool.value)}")
- print([tool.value("layer composition") for tool in plain_tools])
- run.suspend_on_exit()
-
- async with compositor.enter(configs=configs, session_snapshot=run.session_snapshot):
- pass
- print("\nLifecycle:", trace_events)
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/dify-agent/examples/agenton/agenton_examples/pydantic_ai_bridge.py b/dify-agent/examples/agenton/agenton_examples/pydantic_ai_bridge.py
deleted file mode 100644
index 490e54100b9..00000000000
--- a/dify-agent/examples/agenton/agenton_examples/pydantic_ai_bridge.py
+++ /dev/null
@@ -1,119 +0,0 @@
-"""Pydantic AI bridge example for use from a source checkout.
-
-`agenton_examples` is not part of the published package, so run this module from
-the repository root with:
-
- PYTHONPATH=dify-agent/src:dify-agent/examples/agenton \
- uv run --project dify-agent python -m agenton_examples.pydantic_ai_bridge
-"""
-
-from __future__ import annotations
-
-import asyncio
-import os
-from dataclasses import dataclass
-
-from pydantic_ai import Agent, RunContext
-from pydantic_ai.models.openai import OpenAIChatModel # pyright: ignore[reportDeprecated]
-from pydantic_ai.models.test import TestModel
-
-from agenton.compositor import Compositor, LayerNode, LayerProvider
-from agenton_collections.layers.plain import ObjectLayer, PromptLayer, PromptLayerConfig, ToolsLayer
-from agenton_collections.layers.pydantic_ai import PydanticAIBridgeLayer
-from agenton_collections.transformers.pydantic_ai import PYDANTIC_AI_TRANSFORMERS
-
-
-@dataclass(frozen=True, slots=True)
-class AgentProfile:
- name: str
- audience: str
- tone: str
-
-
-def count_words(text: str) -> int:
- return len(text.split())
-
-
-def profile_prompt(ctx: RunContext[AgentProfile]) -> str:
- profile = ctx.deps
- return f"You are {profile.name}, helping {profile.audience}."
-
-
-def tone_prompt(ctx: RunContext[AgentProfile]) -> str:
- return f"Keep responses {ctx.deps.tone}."
-
-
-def write_tagline(ctx: RunContext[AgentProfile], topic: str) -> str:
- profile = ctx.deps
- return f"{profile.name}: {topic} for {profile.audience}, in a {profile.tone} voice."
-
-
-async def main() -> None:
- profile = AgentProfile(
- name="Agenton Assistant",
- audience="engineers composing agent capabilities",
- tone="precise and friendly",
- )
- compositor = Compositor(
- [
- LayerNode("base_prompt", PromptLayer),
- LayerNode(
- "profile",
- LayerProvider.from_factory(
- layer_type=ObjectLayer,
- create=lambda _config: ObjectLayer[AgentProfile](profile),
- ),
- ),
- LayerNode(
- "plain_tools",
- LayerProvider.from_factory(
- layer_type=ToolsLayer,
- create=lambda _config: ToolsLayer(tool_entries=(count_words,)),
- ),
- ),
- LayerNode(
- "pydantic_ai_bridge",
- LayerProvider.from_factory(
- layer_type=PydanticAIBridgeLayer,
- create=lambda _config: PydanticAIBridgeLayer[AgentProfile](
- prefix=("Prefer concrete details.", profile_prompt, tone_prompt),
- user="Use the tools for 'layer composition'.",
- tool_entries=(write_tagline,),
- ),
- ),
- deps={"object_layer": "profile"},
- ),
- ],
- **PYDANTIC_AI_TRANSFORMERS,
- )
-
- async with compositor.enter(
- configs={
- "base_prompt": PromptLayerConfig(
- prefix="Use the available tools before answering.",
- suffix="Return concise, inspectable output.",
- )
- }
- ) as run:
- model = (
- OpenAIChatModel("gpt-5.5") # pyright: ignore[reportDeprecated]
- if os.getenv("OPENAI_API_KEY")
- else TestModel()
- )
- agent = Agent[AgentProfile](
- model=model,
- deps_type=AgentProfile,
- tools=run.tools,
- )
- for prompt in run.prompts:
- _ = agent.system_prompt(prompt)
-
- bridge_layer = run.get_layer("pydantic_ai_bridge", PydanticAIBridgeLayer)
- result = await agent.run(run.user_prompts, deps=bridge_layer.run_deps)
-
- for message in result.all_messages():
- print(message)
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/dify-agent/examples/agenton/agenton_examples/session_snapshot.py b/dify-agent/examples/agenton/agenton_examples/session_snapshot.py
deleted file mode 100644
index 4e5a9c3b9fb..00000000000
--- a/dify-agent/examples/agenton/agenton_examples/session_snapshot.py
+++ /dev/null
@@ -1,50 +0,0 @@
-"""Run with: uv run --project dify-agent python -m agenton_examples.session_snapshot."""
-
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass
-from typing import ClassVar
-
-from pydantic import BaseModel, ConfigDict
-
-from agenton.compositor import Compositor, LayerNode
-from agenton.layers import EmptyLayerConfig, NoLayerDeps, PlainLayer
-
-
-class ConnectionState(BaseModel):
- connection_id: str = "demo-connection"
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-class ConnectionHandle:
- def __init__(self, connection_id: str) -> None:
- self.connection_id = connection_id
-
-
-@dataclass(slots=True)
-class ConnectionLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, ConnectionState]):
- runtime_state_type: ClassVar[type[BaseModel]] = ConnectionState
-
-
-async def main() -> None:
- compositor = Compositor([LayerNode("connection", ConnectionLayer)])
- async with compositor.enter() as run:
- layer = run.get_layer("connection", ConnectionLayer)
- connection = ConnectionHandle(layer.runtime_state.connection_id)
- print("Active external handle:", connection.connection_id)
- run.suspend_on_exit()
-
- snapshot = run.session_snapshot
- assert snapshot is not None
- print("Snapshot:", snapshot.model_dump(mode="json"))
-
- async with compositor.enter(session_snapshot=snapshot) as restored_run:
- layer = restored_run.get_layer("connection", ConnectionLayer)
- restored_connection = ConnectionHandle(f"restored:{layer.runtime_state.connection_id}")
- print("Rehydrated external handle:", restored_connection.connection_id)
-
-
-if __name__ == "__main__":
- asyncio.run(main())
diff --git a/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py b/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py
index 629dd853683..e3c5c15e2d3 100644
--- a/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py
+++ b/dify-agent/examples/dify_agent/dify_agent_examples/__init__.py
@@ -1 +1 @@
-"""Runnable Dify Agent runtime examples kept separate from Agenton examples."""
+"""Runnable Dify Agent client examples."""
diff --git a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py
index 25c9081c1d4..c42d0b4ae32 100644
--- a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py
+++ b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_consumer.py
@@ -7,7 +7,7 @@ example:
uv run --project dify-agent uvicorn dify_agent.server.app:app --reload
-The request carries Dify plugin model configuration in Agenton layers. This
+The request carries Dify plugin model configuration in registered modules. This
script prints the created run and every event observed through cursor polling.
``Client.create_run`` performs one POST attempt only; use polling or SSE replay to
recover after client-side uncertainty.
@@ -15,11 +15,10 @@ recover after client-side uncertainty.
import asyncio
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
+from dify_agent.layers.prompt import Config as PromptConfig
from dify_agent.client import Client
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
DifyPluginLLMLayerConfig,
)
from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, CreateRunRequest, RunComposition, RunLayerSpec
@@ -42,33 +41,33 @@ async def main() -> None:
layers=[
RunLayerSpec(
name="prompt",
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- config=PromptLayerConfig(
- prefix="You are a concise assistant.",
- user="Say hello from the Dify Agent API server example.",
- ),
+ config=(
+ PromptConfig(
+ prefix="You are a concise assistant.",
+ user="Say hello from the Dify Agent API server example.",
+ )
+ ).model_dump(mode="json"),
),
RunLayerSpec(
name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id=TENANT_ID,
- user_id=USER_ID,
- user_from="account",
- app_id=APP_ID,
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
+ config=(
+ DifyExecutionContextLayerConfig(
+ tenant_id=TENANT_ID,
+ user_id=USER_ID,
+ user_from="account",
+ app_id=APP_ID,
+ agent_mode="workflow_run",
+ invoke_from="service-api",
+ )
+ ).model_dump(mode="json"),
),
RunLayerSpec(
name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id=PLUGIN_ID,
- model_provider=PLUGIN_PROVIDER,
- model=MODEL_NAME,
- ),
+ config=(
+ DifyPluginLLMLayerConfig(
+ plugin_id=PLUGIN_ID, model_provider=PLUGIN_PROVIDER, model=MODEL_NAME
+ )
+ ).model_dump(mode="json"),
),
# Minimal plugin-tools example. API callers should pass
# prepared parameters + JSON schema instead of relying on
@@ -82,9 +81,8 @@ async def main() -> None:
# )
# RunLayerSpec(
# name="tools",
- # type="dify.plugin.tools",
- # deps={"execution_context": "execution_context"},
# config=DifyPluginToolsLayerConfig(
+ # execution_context="execution_context",
# tools=[
# DifyPluginToolConfig(
# plugin_id="langgenius/search",
@@ -111,7 +109,7 @@ async def main() -> None:
# },
# )
# ]
- # ),
+ # ).model_dump(mode="json"),
# ),
],
),
diff --git a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py
index 7887329b666..76f4d5ac441 100644
--- a/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py
+++ b/dify-agent/examples/dify_agent/dify_agent_examples/run_server_sync_client.py
@@ -8,11 +8,10 @@ timeout occurs, inspect server state or create a new run explicitly rather than
assuming the original request was not accepted.
"""
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
+from dify_agent.layers.prompt import Config as PromptConfig
from dify_agent.client import Client
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
from dify_agent.layers.dify_plugin import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
DifyPluginLLMLayerConfig,
)
from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, CreateRunRequest, RunComposition, RunLayerSpec
@@ -35,33 +34,33 @@ def main() -> None:
layers=[
RunLayerSpec(
name="prompt",
- type=PLAIN_PROMPT_LAYER_TYPE_ID,
- config=PromptLayerConfig(
- prefix="You are a concise assistant.",
- user="Say hello from the synchronous Dify Agent client example.",
- ),
+ config=(
+ PromptConfig(
+ prefix="You are a concise assistant.",
+ user="Say hello from the synchronous Dify Agent client example.",
+ )
+ ).model_dump(mode="json"),
),
RunLayerSpec(
name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id=TENANT_ID,
- user_id=USER_ID,
- user_from="account",
- app_id=APP_ID,
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
+ config=(
+ DifyExecutionContextLayerConfig(
+ tenant_id=TENANT_ID,
+ user_id=USER_ID,
+ user_from="account",
+ app_id=APP_ID,
+ agent_mode="workflow_run",
+ invoke_from="service-api",
+ )
+ ).model_dump(mode="json"),
),
RunLayerSpec(
name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id=PLUGIN_ID,
- model_provider=PLUGIN_PROVIDER,
- model=MODEL_NAME,
- ),
+ config=(
+ DifyPluginLLMLayerConfig(
+ plugin_id=PLUGIN_ID, model_provider=PLUGIN_PROVIDER, model=MODEL_NAME
+ )
+ ).model_dump(mode="json"),
),
# Minimal plugin-tools example. API callers should pass
# prepared parameters + JSON schema instead of relying on
@@ -75,9 +74,8 @@ def main() -> None:
# )
# RunLayerSpec(
# name="tools",
- # type="dify.plugin.tools",
- # deps={"execution_context": "execution_context"},
# config=DifyPluginToolsLayerConfig(
+ # execution_context="execution_context",
# tools=[
# DifyPluginToolConfig(
# plugin_id="langgenius/search",
@@ -104,7 +102,7 @@ def main() -> None:
# },
# )
# ]
- # ),
+ # ).model_dump(mode="json"),
# ),
],
),
diff --git a/dify-agent/mkdocs.yml b/dify-agent/mkdocs.yml
index 5842702d8d3..ac3bf216585 100644
--- a/dify-agent/mkdocs.yml
+++ b/dify-agent/mkdocs.yml
@@ -1,5 +1,5 @@
site_name: Dify Agent
-site_description: Agent runtime and Agenton composition framework documentation
+site_description: Native Pydantic AI agent runtime documentation
strict: true
repo_name: langgenius/dify
@@ -8,10 +8,6 @@ edit_uri: edit/main/dify-agent/docs/
nav:
- Home: index.md
- - Agenton:
- - Overview: agenton/index.md
- - Guide: agenton/guide/index.md
- - Examples: agenton/examples/index.md
- Dify Agent:
- Overview: dify-agent/index.md
- Concepts:
@@ -19,14 +15,13 @@ nav:
- Runtime Resources: dify-agent/concepts/runtime-resources/index.md
- User Manual:
- Get Started: dify-agent/get-started/index.md
- - Prompt Layer: dify-agent/user-manual/prompt-layer/index.md
- - Execution Context Layer: dify-agent/user-manual/execution-context-layer/index.md
- - Shell Layer: dify-agent/user-manual/shell-layer/index.md
- - Ask Human Layer: dify-agent/user-manual/ask-human-layer/index.md
- - Plugin LLM Layer: dify-agent/user-manual/plugin-llm-layer/index.md
- - Plugin Tool Layer: dify-agent/user-manual/plugin-tool-layer/index.md
- - History Layer: dify-agent/user-manual/history-layer/index.md
- - Structured Output Layer: dify-agent/user-manual/structured-output-layer/index.md
+ - Prompt Module: dify-agent/user-manual/prompt-layer/index.md
+ - Execution Context Module: dify-agent/user-manual/execution-context-layer/index.md
+ - Shell Module: dify-agent/user-manual/shell-layer/index.md
+ - Plugin LLM Module: dify-agent/user-manual/plugin-llm-layer/index.md
+ - Plugin Tool Module: dify-agent/user-manual/plugin-tool-layer/index.md
+ - History Module: dify-agent/user-manual/history-layer/index.md
+ - Structured Output Module: dify-agent/user-manual/structured-output-layer/index.md
- Operations Guide:
- Overview: dify-agent/guide/index.md
- OpenShell Runtime Backend: dify-agent/guide/openshell.md
diff --git a/dify-agent/pyproject.toml b/dify-agent/pyproject.toml
index a6549f7fcbc..1c29370e03c 100644
--- a/dify-agent/pyproject.toml
+++ b/dify-agent/pyproject.toml
@@ -9,7 +9,7 @@ dependencies = [
"httpx2>=2.5.0,<3.0.0",
"pydantic>=2.12.5,<2.13",
"pydantic-ai-harness>=0.20.0,<0.21.0",
- "pydantic-ai-slim>=2.30.0,<3.0.0",
+ "pydantic-ai-slim==2.31.0",
"typing-extensions>=4.12.2,<5.0.0",
]
@@ -29,7 +29,7 @@ server = [
"jwcrypto>=1.5.6,<2",
"logfire[fastapi,httpx,redis]>=4.37.0,<5.0.0",
"openshell>=0.0.106,<0.1.0",
- "pydantic-ai-slim[anthropic,google,openai]>=2.30.0,<3.0.0",
+ "pydantic-ai-slim[anthropic,google,openai]==2.31.0",
"pydantic-settings>=2.12.0,<3.0.0",
"redis>=7.4.0,<8.0.0",
"uvicorn[standard]==0.46.0",
@@ -37,7 +37,7 @@ server = [
[tool.setuptools.packages.find]
where = ["src"]
-include = ["agenton*", "agenton_collections*", "dify_agent*", "shellctl*"]
+include = ["dify_agent*", "shellctl*"]
[tool.setuptools.package-data]
"dify_agent.layers" = ["_agent_cli_help.json"]
@@ -45,9 +45,10 @@ include = ["agenton*", "agenton_collections*", "dify_agent*", "shellctl*"]
[tool.pyrefly]
project-includes = ["src", "examples"]
project-excludes = [".venv", "tests/"]
-search-path = ["src", "examples/agenton", "examples/dify_agent"]
+search-path = ["src", "examples/dify_agent"]
python-platform = "linux"
python-version = "3.13.0"
+errors = { missing-override-decorator = "error" }
[tool.pytest.ini_options]
# Several test modules share a basename across directories (test_layer.py,
diff --git a/dify-agent/src/agenton/__init__.py b/dify-agent/src/agenton/__init__.py
deleted file mode 100644
index 13f624c6bcd..00000000000
--- a/dify-agent/src/agenton/__init__.py
+++ /dev/null
@@ -1,19 +0,0 @@
-"""Agenton state-only core.
-
-Agenton core composes reusable stateless layer graph plans, creates a fresh
-``CompositorRun`` for each invocation, hydrates and advances serializable layer
-``runtime_state`` through run slots, enters each layer's active-scope
-``resource_context()``, and emits session snapshots. It intentionally never
-serializes resources, handles, clients, cleanup callbacks, or any other
-non-serializable runtime object.
-
-Each ``Compositor`` stores only graph nodes and layer providers. Every enter call
-creates new layer instances, binds direct dependencies for that run, and writes
-the next cross-call state to ``run.session_snapshot`` after exit. To resume a
-suspended call, reuse the same compositor plan and pass the prior snapshot to a
-new enter call.
-
-``LifecycleState.ACTIVE`` is internal-only while an entry is running. External
-session snapshots and hydrated input must contain only non-active lifecycle
-states; ``runtime_state`` is the only mutable layer data captured by snapshots.
-"""
diff --git a/dify-agent/src/agenton/compositor/__init__.py b/dify-agent/src/agenton/compositor/__init__.py
deleted file mode 100644
index 17829fe3e41..00000000000
--- a/dify-agent/src/agenton/compositor/__init__.py
+++ /dev/null
@@ -1,56 +0,0 @@
-"""Stateless layer graph composition facade for the Agenton core.
-
-``agenton.compositor`` remains the stable import surface for reusable graph
-composition. ``core.py`` defines the state-only ``Compositor`` graph plan and
-``LayerNode`` orchestration, ``providers.py`` owns reusable construction plans
-and fresh-instance validation, ``run.py`` owns active invocation lifecycle plus
-prompt/tool aggregation, ``schemas.py`` owns serializable graph/snapshot DTOs
-and boundary revalidation, and ``types.py`` holds shared generic transformer
-types.
-
-``Compositor`` itself stores no live layer instances, run lifecycle state,
-session state, resources, or handles. Each ``enter(...)`` call creates a fresh
-``CompositorRun`` with new layer instances, direct dependency binding, optional
-snapshot hydration, entered per-layer ``resource_context()`` scopes, and the
-next ``session_snapshot`` after exit.
-``LifecycleState.ACTIVE`` remains internal-only and session snapshots contain
-only ordered layer lifecycle state plus serializable ``runtime_state``.
-
-The facade also keeps true module-level aliases for ``LayerConfigInput`` and
-``LayerProviderInput`` so existing typed direct imports remain supported
-without expanding ``__all__``.
-"""
-
-from .core import Compositor, LayerNode
-from .providers import LayerConfigInput as _LayerConfigInput
-from .providers import LayerFactory, LayerProvider, LayerProviderInput as _LayerProviderInput
-from .run import CompositorRun, LayerRunSlot
-from .schemas import (
- CompositorConfig,
- CompositorConfigValue,
- CompositorSessionSnapshot,
- CompositorSessionSnapshotValue,
- LayerNodeConfig,
- LayerSessionSnapshot,
-)
-from .types import CompositorTransformer, CompositorTransformerKwargs
-
-type LayerConfigInput = _LayerConfigInput
-type LayerProviderInput = _LayerProviderInput
-
-__all__ = [
- "Compositor",
- "CompositorConfig",
- "CompositorConfigValue",
- "CompositorRun",
- "CompositorSessionSnapshot",
- "CompositorSessionSnapshotValue",
- "CompositorTransformer",
- "CompositorTransformerKwargs",
- "LayerFactory",
- "LayerNode",
- "LayerNodeConfig",
- "LayerProvider",
- "LayerRunSlot",
- "LayerSessionSnapshot",
-]
diff --git a/dify-agent/src/agenton/compositor/core.py b/dify-agent/src/agenton/compositor/core.py
deleted file mode 100644
index eb3763b2f76..00000000000
--- a/dify-agent/src/agenton/compositor/core.py
+++ /dev/null
@@ -1,331 +0,0 @@
-"""Stateless compositor graph plans and run construction.
-
-``Compositor`` stores only reusable graph nodes and optional aggregation
-transformers. Each ``enter(...)`` call validates node-name keyed configs before
-any provider factory runs, optionally validates and hydrates a session snapshot,
-creates fresh layer instances, binds direct dependencies, and returns a new
-``CompositorRun`` for that invocation only. Dependency targets must point to
-preceding graph nodes so resource scopes can nest in dependency order.
-
-``Compositor.from_config(...)`` resolves serializable provider type ids rather
-than import paths. Named ``node_providers`` override type-id providers for the
-same graph node without passing graph node data into factories. Session
-snapshots must list layer names in compositor order so runtime state can be
-hydrated deterministically.
-"""
-
-from collections import OrderedDict
-from collections.abc import AsyncGenerator, Mapping, Sequence
-from contextlib import asynccontextmanager
-from dataclasses import dataclass
-from typing import Any, Generic, Self, cast
-
-from pydantic import JsonValue
-
-from agenton.layers.base import Layer, LayerConfig, LifecycleState
-
-from .providers import LayerConfigInput, LayerProvider, LayerProviderInput, _as_layer_provider
-from .run import CompositorRun, LayerRunSlot
-from .schemas import (
- CompositorConfigValue,
- CompositorSessionSnapshot,
- CompositorSessionSnapshotValue,
- _validate_compositor_config_input,
- _validate_config_model_input,
-)
-from .types import (
- CompositorTransformer,
- LayerPromptT,
- LayerToolT,
- LayerUserPromptT,
- PromptT,
- ToolT,
- UserPromptT,
-)
-
-
-@dataclass(frozen=True, slots=True, init=False)
-class LayerNode:
- """Stateless graph node plan for one named layer provider.
-
- ``implementation`` may be a layer class or an explicit ``LayerProvider``.
- ``deps`` maps dependency field names on this node's layer class to other
- preceding compositor node names. ``metadata`` is graph description data
- only; it is not passed to provider factories and is never included in
- session snapshots.
- """
-
- name: str
- provider: LayerProvider[Any]
- deps: Mapping[str, str]
- metadata: Mapping[str, JsonValue]
-
- def __init__(
- self,
- name: str,
- implementation: LayerProviderInput,
- *,
- deps: Mapping[str, str] | None = None,
- metadata: Mapping[str, JsonValue] | None = None,
- ) -> None:
- if not name:
- raise ValueError("Layer node name must not be empty.")
- object.__setattr__(self, "name", name)
- object.__setattr__(self, "provider", _as_layer_provider(implementation))
- object.__setattr__(self, "deps", dict(deps or {}))
- object.__setattr__(self, "metadata", dict(metadata or {}))
-
-
-class Compositor(Generic[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]):
- """Reusable, framework-neutral ordered layer graph plan.
-
- A compositor stores only immutable graph nodes and provider construction
- plans. It is safe to enter repeatedly or concurrently because every entry
- creates a separate ``CompositorRun`` with fresh layer instances, run slots,
- dependency bindings, and optional hydrated runtime state. Session
- continuity is explicit: pass the previous ``CompositorSessionSnapshot`` to
- the next ``enter`` call and read the next one from ``run.session_snapshot``
- after exit.
-
- ``prompt_transformer``, ``user_prompt_transformer``, and
- ``tool_transformer`` are post-aggregation hooks on each run. Use two type
- arguments for identity aggregation, four when prompt/tool layer item types
- differ from exposed item types, or all six when user prompt item types also
- differ. Graph order is meaningful for lifecycle nesting, so dependency edges
- must point only to earlier nodes.
- """
-
- __slots__ = ("_nodes", "prompt_transformer", "tool_transformer", "user_prompt_transformer")
-
- _nodes: tuple[LayerNode, ...]
- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None
- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None
- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None
-
- def __init__(
- self,
- nodes: Sequence[LayerNode],
- *,
- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None = None,
- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None = None,
- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None = None,
- ) -> None:
- self._nodes = tuple(nodes)
- self.prompt_transformer = prompt_transformer
- self.user_prompt_transformer = user_prompt_transformer
- self.tool_transformer = tool_transformer
- self._validate_nodes()
-
- @property
- def nodes(self) -> tuple[LayerNode, ...]:
- """Return the stateless graph plan nodes in compositor order."""
- return self._nodes
-
- @classmethod
- def from_config(
- cls,
- conf: CompositorConfigValue,
- *,
- providers: Sequence[LayerProviderInput],
- node_providers: Mapping[str, LayerProviderInput] | None = None,
- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None = None,
- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None = None,
- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None = None,
- ) -> Self:
- """Create a reusable compositor plan from serializable graph config.
-
- ``providers`` resolve graph node ``type`` ids. ``node_providers`` are
- keyed by graph node name and take precedence over the type-id provider,
- allowing node-specific construction without passing node data to factory
- callables.
- """
- graph_config = _validate_compositor_config_input(conf)
- if graph_config.schema_version != 1:
- raise ValueError(f"Unsupported compositor config schema_version: {graph_config.schema_version}.")
-
- provider_by_type = _build_provider_type_map(providers)
- provider_by_node = {name: _as_layer_provider(provider) for name, provider in (node_providers or {}).items()}
- graph_node_names = {node.name for node in graph_config.layers}
- unknown_node_providers = provider_by_node.keys() - graph_node_names
- if unknown_node_providers:
- names = ", ".join(sorted(unknown_node_providers))
- raise ValueError(f"node_providers contains unknown layer node names: {names}.")
-
- nodes: list[LayerNode] = []
- for node_config in graph_config.layers:
- provider = provider_by_node.get(node_config.name)
- if provider is None:
- try:
- provider = provider_by_type[node_config.type]
- except KeyError as e:
- raise KeyError(f"Layer type id '{node_config.type}' is not registered.") from e
- nodes.append(
- LayerNode(
- node_config.name,
- provider,
- deps=node_config.deps,
- metadata=node_config.metadata,
- )
- )
-
- return cls(
- nodes,
- prompt_transformer=prompt_transformer,
- user_prompt_transformer=user_prompt_transformer,
- tool_transformer=tool_transformer,
- )
-
- @asynccontextmanager
- async def enter(
- self,
- *,
- configs: Mapping[str, LayerConfigInput] | None = None,
- session_snapshot: CompositorSessionSnapshotValue | None = None,
- ) -> AsyncGenerator[CompositorRun[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]]:
- """Create a fresh run, enter layers in graph order, and yield it.
-
- Configs are keyed by layer node name and validated before factories run.
- The optional session snapshot is validated and hydrated before any hook
- runs. Layers exit in reverse graph order, and ``run.session_snapshot``
- is populated after exit with the next non-active lifecycle states.
- """
- run = self._create_run(configs=configs, session_snapshot=session_snapshot)
- await run._enter_layers()
- body_error: BaseException | None = None
- try:
- yield run
- except BaseException as exc:
- body_error = exc
- raise
- finally:
- await run._exit_layers(body_error)
-
- def _create_run(
- self,
- *,
- configs: Mapping[str, LayerConfigInput] | None,
- session_snapshot: CompositorSessionSnapshotValue | None,
- ) -> CompositorRun[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]:
- config_by_name = self._validate_run_configs(configs)
- typed_config_by_name = self._validate_layer_configs(config_by_name)
- snapshot = self._validate_session_snapshot(session_snapshot) if session_snapshot is not None else None
- layer_by_name = self._create_layers(typed_config_by_name)
-
- snapshot_by_name = (
- {layer_snapshot.name: layer_snapshot for layer_snapshot in snapshot.layers} if snapshot else {}
- )
- lifecycle_by_name: dict[str, LifecycleState] = {}
- for node in self._nodes:
- layer = layer_by_name[node.name]
- layer_snapshot = snapshot_by_name.get(node.name)
- if layer_snapshot is None:
- lifecycle_by_name[node.name] = LifecycleState.NEW
- continue
- layer.runtime_state = cast(Any, layer.runtime_state_type.model_validate(layer_snapshot.runtime_state))
- lifecycle_by_name[node.name] = layer_snapshot.lifecycle_state
-
- self._bind_deps(layer_by_name)
- return CompositorRun(
- slots=OrderedDict(
- (node.name, LayerRunSlot(layer=layer_by_name[node.name], lifecycle_state=lifecycle_by_name[node.name]))
- for node in self._nodes
- ),
- prompt_transformer=self.prompt_transformer,
- user_prompt_transformer=self.user_prompt_transformer,
- tool_transformer=self.tool_transformer,
- )
-
- def _create_layers(
- self,
- config_by_name: Mapping[str, LayerConfig],
- ) -> OrderedDict[str, Layer[Any, Any, Any, Any, Any, Any]]:
- return OrderedDict(
- (node.name, node.provider.create_layer_from_config(config_by_name[node.name])) for node in self._nodes
- )
-
- def _validate_layer_configs(self, config_by_name: Mapping[str, LayerConfigInput]) -> dict[str, LayerConfig]:
- """Validate every node config before any provider factory is invoked."""
- return {node.name: node.provider.validate_config(config_by_name.get(node.name)) for node in self._nodes}
-
- def _bind_deps(self, layer_by_name: Mapping[str, Layer[Any, Any, Any, Any, Any, Any]]) -> None:
- """Resolve dependency-name mappings and bind direct layer dependencies."""
- for node in self._nodes:
- layer = layer_by_name[node.name]
- resolved_deps = {dep_name: layer_by_name[target_name] for dep_name, target_name in node.deps.items()}
- layer.bind_deps(resolved_deps)
-
- def _validate_nodes(self) -> None:
- layer_names: set[str] = set()
- for node in self._nodes:
- if node.name in layer_names:
- raise ValueError(f"Duplicate layer name '{node.name}'.")
- layer_names.add(node.name)
-
- layer_index_by_name = {node.name: index for index, node in enumerate(self._nodes)}
-
- for node in self._nodes:
- declared_deps = node.provider.layer_type.dependency_names()
- unknown_dep_keys = set(node.deps) - declared_deps
- if unknown_dep_keys:
- names = ", ".join(sorted(unknown_dep_keys))
- raise ValueError(f"Layer '{node.name}' declares unknown dependency keys: {names}.")
- missing_targets = set(node.deps.values()) - layer_names
- if missing_targets:
- names = ", ".join(sorted(missing_targets))
- raise ValueError(f"Layer '{node.name}' depends on undefined layer names: {names}.")
-
- non_preceding_targets = {
- dep_name: target_name
- for dep_name, target_name in node.deps.items()
- if layer_index_by_name[target_name] >= layer_index_by_name[node.name]
- }
- if non_preceding_targets:
- targets = ", ".join(
- f"{dep_name}->{target_name}" for dep_name, target_name in sorted(non_preceding_targets.items())
- )
- raise ValueError(
- f"Layer '{node.name}' dependencies must target preceding layer nodes in compositor order: "
- f"{targets}."
- )
-
- def _validate_run_configs(self, configs: Mapping[str, LayerConfigInput] | None) -> dict[str, LayerConfigInput]:
- config_by_name = dict(configs or {})
- known_names = {node.name for node in self._nodes}
- unknown_names = config_by_name.keys() - known_names
- if unknown_names:
- names = ", ".join(sorted(unknown_names))
- raise ValueError(f"Layer configs contain unknown layer node names: {names}.")
- return config_by_name
-
- def _validate_session_snapshot(
- self,
- snapshot: CompositorSessionSnapshotValue,
- ) -> CompositorSessionSnapshot:
- resolved_snapshot = _validate_config_model_input(CompositorSessionSnapshot, snapshot)
- if resolved_snapshot.schema_version != 1:
- raise ValueError(
- f"Unsupported compositor session snapshot schema_version: {resolved_snapshot.schema_version}."
- )
- expected_layer_names = tuple(node.name for node in self._nodes)
- actual_layer_names = tuple(layer.name for layer in resolved_snapshot.layers)
- if actual_layer_names != expected_layer_names:
- expected = ", ".join(expected_layer_names)
- actual = ", ".join(actual_layer_names)
- raise ValueError(
- "CompositorSessionSnapshot layer names must match compositor layers in order. "
- f"Expected [{expected}], got [{actual}]."
- )
- return resolved_snapshot
-
-
-def _build_provider_type_map(providers: Sequence[LayerProviderInput]) -> dict[str, LayerProvider[Any]]:
- provider_by_type: dict[str, LayerProvider[Any]] = {}
- for provider_input in providers:
- provider = _as_layer_provider(provider_input)
- type_id = provider.type_id
- if type_id is None or not type_id:
- raise ValueError(f"Layer provider for '{provider.layer_type.__qualname__}' must declare a type_id.")
- if type_id in provider_by_type:
- raise ValueError(f"Layer type id '{type_id}' is already registered.")
- provider_by_type[type_id] = provider
- return provider_by_type
diff --git a/dify-agent/src/agenton/compositor/providers.py b/dify-agent/src/agenton/compositor/providers.py
deleted file mode 100644
index 7f176cec908..00000000000
--- a/dify-agent/src/agenton/compositor/providers.py
+++ /dev/null
@@ -1,138 +0,0 @@
-"""Reusable layer providers and fresh-instance validation.
-
-Providers are construction plans, not live runtime owners. They validate raw
-per-enter config into a layer's declared ``config_type`` and then construct a
-fresh layer instance for one invocation. Provider factories receive only typed
-config, never graph node data; node-specific construction belongs in named
-``node_providers`` overrides on ``Compositor.from_config(...)``.
-
-Fresh-instance enforcement is global by weak reference so ``Compositor`` can
-stay stateless while still rejecting reused layer instances before dependency
-binding or lifecycle hooks run.
-"""
-
-from collections.abc import Callable, Mapping
-from typing import Any, Generic, cast
-import weakref
-
-from agenton.layers.base import Layer, LayerConfig, LayerConfigValue
-
-from .schemas import _validate_config_model_input
-from .types import LayerT
-
-type LayerConfigInput = LayerConfigValue | Mapping[str, object] | str | bytes | None
-type LayerFactory = Callable[[LayerConfig], Layer[Any, Any, Any, Any, Any, Any]]
-type LayerProviderInput = type[Layer[Any, Any, Any, Any, Any, Any]] | "LayerProvider[Any]"
-
-
-_USED_LAYER_INSTANCE_REFS: dict[int, weakref.ReferenceType[Layer[Any, Any, Any, Any, Any, Any]]] = {}
-
-
-def _claim_fresh_layer_instance(layer: Layer[Any, Any, Any, Any, Any, Any]) -> None:
- """Reject provider factories that return a layer object used before.
-
- The registry stores weak references, not live resources or run state. It is
- intentionally global to keep ``Compositor`` stateless while still enforcing
- the fresh-instance boundary before dependencies are bound or hooks run.
- """
- layer_identity = id(layer)
- existing_ref = _USED_LAYER_INSTANCE_REFS.get(layer_identity)
- if existing_ref is not None:
- existing_layer = existing_ref()
- if existing_layer is not None:
- raise ValueError(
- "LayerProvider factories must return a fresh layer instance for each invocation; "
- f"got reused instance of '{type(layer).__name__}'."
- )
- _USED_LAYER_INSTANCE_REFS.pop(layer_identity, None)
-
- def remove_ref(ref: weakref.ReferenceType[Layer[Any, Any, Any, Any, Any, Any]]) -> None:
- if _USED_LAYER_INSTANCE_REFS.get(layer_identity) is ref:
- _USED_LAYER_INSTANCE_REFS.pop(layer_identity, None)
-
- _USED_LAYER_INSTANCE_REFS[layer_identity] = weakref.ref(layer, remove_ref)
-
-
-class LayerProvider(Generic[LayerT]):
- """Validated layer factory for one concrete ``Layer`` class.
-
- Providers are reusable construction plans. They validate per-call config
- with ``layer_type.config_type`` before invoking either
- ``layer_type.from_config`` or a custom factory. The factory receives only
- typed config, never graph node data, and must return a fresh ``layer_type``
- instance; reused instances are rejected before dependencies are bound or
- hooks run.
- """
-
- __slots__ = ("_create", "layer_type")
-
- layer_type: type[LayerT]
- _create: Callable[[LayerConfig], LayerT]
-
- def __init__(self, *, layer_type: type[LayerT], create: Callable[[LayerConfig], LayerT]) -> None:
- self.layer_type = layer_type
- self._create = create
-
- @classmethod
- def from_layer_type(cls, layer_type: type[LayerT]) -> "LayerProvider[LayerT]":
- """Create a provider that constructs layers via ``layer_type.from_config``."""
-
- def create(config: LayerConfig) -> LayerT:
- return layer_type.from_config(cast(Any, config))
-
- return cls(layer_type=layer_type, create=create)
-
- @classmethod
- def from_factory(
- cls,
- *,
- layer_type: type[LayerT],
- create: Callable[[Any], LayerT],
- ) -> "LayerProvider[LayerT]":
- """Create a provider from a custom typed-config factory.
-
- ``create`` receives the validated instance of ``layer_type.config_type``.
- It does not receive the graph node; node-specific construction should use
- a dedicated provider in ``Compositor.from_config(node_providers=...)``.
- """
- return cls(layer_type=layer_type, create=cast(Callable[[LayerConfig], LayerT], create))
-
- @property
- def type_id(self) -> str | None:
- """Return the serializable registry type id declared by ``layer_type``."""
- return self.layer_type.type_id
-
- def create_layer(self, config: LayerConfigInput = None) -> LayerT:
- """Validate config, call the factory, and return a fresh layer instance."""
- typed_config = self.validate_config(config)
- return self.create_layer_from_config(typed_config)
-
- def validate_config(self, config: LayerConfigInput = None) -> LayerConfig:
- """Return typed config without invoking the layer factory.
-
- ``Compositor.enter`` calls this for every node before creating any layer
- so a later invalid node config cannot leave earlier factory side effects.
- """
- raw_config: LayerConfigValue | Mapping[str, object] | str | bytes = {} if config is None else config
- return _validate_config_model_input(self.layer_type.config_type, raw_config)
-
- def create_layer_from_config(self, config: LayerConfig) -> LayerT:
- """Call the factory with validated config and enforce fresh instances."""
- typed_config = self.validate_config(config)
- layer = self._create(typed_config)
- if not isinstance(layer, self.layer_type):
- raise TypeError(
- f"LayerProvider for '{self.layer_type.__name__}' returned '{type(layer).__name__}', "
- f"expected '{self.layer_type.__name__}'."
- )
- _claim_fresh_layer_instance(layer)
- layer.config = cast(Any, typed_config)
- return layer
-
-
-def _as_layer_provider(implementation: LayerProviderInput) -> LayerProvider[Any]:
- if isinstance(implementation, LayerProvider):
- return implementation
- if isinstance(implementation, type) and issubclass(implementation, Layer):
- return LayerProvider.from_layer_type(implementation)
- raise TypeError("LayerNode implementation must be a Layer subclass or LayerProvider.")
diff --git a/dify-agent/src/agenton/compositor/run.py b/dify-agent/src/agenton/compositor/run.py
deleted file mode 100644
index 95fa3451595..00000000000
--- a/dify-agent/src/agenton/compositor/run.py
+++ /dev/null
@@ -1,278 +0,0 @@
-"""Active compositor run lifecycle, snapshots, and aggregation.
-
-``CompositorRun`` is the only compositor object that exposes live layer
-instances. It owns invocation-local lifecycle state, per-layer exit intent,
-entered layer resource scopes, and the next ``session_snapshot`` after exit.
-Layers enter in graph order and exit in reverse graph order. A layer's
-``resource_context()`` wraps that layer's enter hook, the active run body while
-the layer remains active, and the layer's exit hook. Prompt aggregation
-preserves graph ordering: prefix prompts first-to-last, suffix prompts
-last-to-first, user prompts first-to-last, and tools in graph order.
-
-Enter hooks transition a slot to ``LifecycleState.ACTIVE`` only after returning
-successfully. If ``on_context_create`` or ``on_context_resume`` raises, the run
-still exits any already-entered resource contexts, but it does not call the
-layer's normal suspend/delete hook for that failed enter attempt.
-
-Prompt, user prompt, and tool transformers run only after layer-level wrapping
-and run-level aggregation. When no transformer is installed, the wrapped items
-are returned unchanged.
-"""
-
-from collections import OrderedDict
-from collections.abc import Sequence
-from contextlib import AbstractAsyncContextManager
-from dataclasses import dataclass
-from typing import Any, Generic, cast, overload
-
-from pydantic import JsonValue
-
-from agenton.layers.base import ExitIntent, Layer, LifecycleState
-
-from .schemas import CompositorSessionSnapshot, LayerSessionSnapshot
-from .types import (
- CompositorTransformer,
- LayerPromptT,
- LayerT,
- LayerToolT,
- LayerUserPromptT,
- PromptT,
- ToolT,
- UserPromptT,
-)
-
-
-@dataclass(slots=True)
-class LayerRunSlot:
- """Invocation-local lifecycle, resource scope, and exit state for one layer."""
-
- layer: Layer[Any, Any, Any, Any, Any, Any]
- lifecycle_state: LifecycleState
- exit_intent: ExitIntent = ExitIntent.DELETE
- active_resource_context: AbstractAsyncContextManager[None] | None = None
-
-
-@dataclass(slots=True)
-class CompositorRun(Generic[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT]):
- """Single-invocation runtime object created by ``Compositor.enter``.
-
- The run owns ordered ``LayerRunSlot`` objects and the fresh layers inside
- them. It is the only object that exposes live layers, lifecycle state, exit
- intent, and prompt/user-prompt/tool aggregation for an active invocation.
- After context exit, ``session_snapshot`` contains the next cross-call state.
- """
-
- slots: OrderedDict[str, LayerRunSlot]
- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT] | None = None
- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT] | None = None
- tool_transformer: CompositorTransformer[LayerToolT, ToolT] | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
-
- @overload
- def get_layer(self, name: str) -> Layer[Any, Any, Any, Any, Any, Any]: ...
-
- @overload
- def get_layer(self, name: str, layer_type: type[LayerT]) -> LayerT: ...
-
- def get_layer(
- self,
- name: str,
- layer_type: type[LayerT] | None = None,
- ) -> Layer[Any, Any, Any, Any, Any, Any] | LayerT:
- """Return a live layer by node name and optionally validate its type."""
- try:
- layer = self.slots[name].layer
- except KeyError as e:
- raise KeyError(f"Layer '{name}' is not defined in this compositor run.") from e
-
- if layer_type is not None and not isinstance(layer, layer_type):
- raise TypeError(f"Layer '{name}' must be {layer_type.__name__}, got {type(layer).__name__}.")
- return layer
-
- def suspend_on_exit(self) -> None:
- """Request suspend behavior for every active layer when the run exits."""
- for name in self.slots:
- self.suspend_layer_on_exit(name)
-
- def delete_on_exit(self) -> None:
- """Request delete behavior for every active layer when the run exits."""
- for name in self.slots:
- self.delete_layer_on_exit(name)
-
- def suspend_layer_on_exit(self, name: str) -> None:
- """Request suspend behavior for one active layer when the run exits."""
- self._set_layer_exit_intent(name, ExitIntent.SUSPEND)
-
- def delete_layer_on_exit(self, name: str) -> None:
- """Request delete behavior for one active layer when the run exits."""
- self._set_layer_exit_intent(name, ExitIntent.DELETE)
-
- def snapshot_session(self) -> CompositorSessionSnapshot:
- """Snapshot non-active layer lifecycle state and runtime state from this run."""
- active_layers = [name for name, slot in self.slots.items() if slot.lifecycle_state is LifecycleState.ACTIVE]
- if active_layers:
- names = ", ".join(active_layers)
- raise RuntimeError(f"Cannot snapshot active compositor run layers: {names}.")
- return CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(
- name=name,
- lifecycle_state=slot.lifecycle_state,
- runtime_state=cast(dict[str, JsonValue], slot.layer.runtime_state.model_dump(mode="json")),
- )
- for name, slot in self.slots.items()
- ]
- )
-
- async def _enter_layers(self) -> None:
- self._ensure_layers_can_enter()
- entered_slots: list[LayerRunSlot] = []
- try:
- for slot in self.slots.values():
- await self._enter_slot(slot)
- entered_slots.append(slot)
- except BaseException as enter_error:
- hook_error = await self._exit_slots_reversed(entered_slots, wrapped_error=enter_error)
- self.session_snapshot = self.snapshot_session()
- if hook_error is not None:
- raise hook_error from enter_error
- raise
-
- async def _exit_layers(self, wrapped_error: BaseException | None = None) -> None:
- hook_error = await self._exit_slots_reversed(list(self.slots.values()), wrapped_error=wrapped_error)
- self.session_snapshot = self.snapshot_session()
- if hook_error is not None:
- raise hook_error
-
- async def _enter_slot(self, slot: LayerRunSlot) -> None:
- resource_context = slot.layer.resource_context()
- await resource_context.__aenter__()
- slot.active_resource_context = resource_context
- try:
- if slot.lifecycle_state is LifecycleState.NEW:
- slot.exit_intent = ExitIntent.DELETE
- await slot.layer.on_context_create()
- slot.lifecycle_state = LifecycleState.ACTIVE
- return
- if slot.lifecycle_state is LifecycleState.SUSPENDED:
- slot.exit_intent = ExitIntent.DELETE
- await slot.layer.on_context_resume()
- slot.lifecycle_state = LifecycleState.ACTIVE
- return
- raise RuntimeError(f"Cannot enter layer from lifecycle state '{slot.lifecycle_state}'.")
- except BaseException as enter_error:
- resource_error = await self._exit_resource_context(slot, wrapped_error=enter_error)
- if resource_error is not None:
- raise resource_error from enter_error
- raise
-
- async def _exit_slots_reversed(
- self,
- slots: Sequence[LayerRunSlot],
- *,
- wrapped_error: BaseException | None = None,
- ) -> BaseException | None:
- hook_error: BaseException | None = None
- propagating_error = wrapped_error
- for slot in reversed(slots):
- if slot.lifecycle_state is not LifecycleState.ACTIVE:
- continue
- slot_error: BaseException | None = None
- if slot.exit_intent is ExitIntent.SUSPEND:
- try:
- await slot.layer.on_context_suspend()
- except BaseException as exc:
- slot_error = exc
- hook_error = hook_error or exc
- finally:
- slot.lifecycle_state = LifecycleState.SUSPENDED
- else:
- try:
- await slot.layer.on_context_delete()
- except BaseException as exc:
- slot_error = exc
- hook_error = hook_error or exc
- finally:
- slot.lifecycle_state = LifecycleState.CLOSED
-
- slot_scope_error = slot_error or propagating_error
- resource_error = await self._exit_resource_context(slot, wrapped_error=slot_scope_error)
- if resource_error is not None:
- hook_error = hook_error or resource_error
- propagating_error = resource_error
- continue
- propagating_error = slot_scope_error
-
- return hook_error
-
- async def _exit_resource_context(
- self,
- slot: LayerRunSlot,
- *,
- wrapped_error: BaseException | None,
- ) -> BaseException | None:
- resource_context = slot.active_resource_context
- if resource_context is None:
- return None
-
- slot.active_resource_context = None
- exc_type = type(wrapped_error) if wrapped_error is not None else None
- exc_traceback = wrapped_error.__traceback__ if wrapped_error is not None else None
- try:
- # Resource scopes exist for deterministic live-resource cleanup. They
- # should observe the exception leaving the wrapped scope, but Agenton
- # still preserves its own hook/body error propagation rules.
- await resource_context.__aexit__(exc_type, wrapped_error, exc_traceback)
- except BaseException as exc:
- return exc
- return None
-
- def _set_layer_exit_intent(self, name: str, intent: ExitIntent) -> None:
- try:
- slot = self.slots[name]
- except KeyError as e:
- raise KeyError(f"Layer '{name}' is not defined in this compositor run.") from e
- if slot.lifecycle_state is not LifecycleState.ACTIVE:
- raise RuntimeError("Layer exit intent can only be changed while the run slot is active.")
- slot.exit_intent = intent
-
- def _ensure_layers_can_enter(self) -> None:
- """Reject invalid external lifecycle states before any layer side effects."""
- for name, slot in self.slots.items():
- if slot.lifecycle_state is LifecycleState.ACTIVE:
- raise RuntimeError(f"Layer '{name}' is already active; ACTIVE snapshots are not allowed.")
- if slot.lifecycle_state is LifecycleState.CLOSED:
- raise RuntimeError(f"Layer '{name}' is closed; CLOSED snapshots cannot be entered.")
-
- @property
- def prompts(self) -> list[PromptT]:
- result: list[LayerPromptT] = []
- for slot in self.slots.values():
- layer = slot.layer
- result.extend(cast(LayerPromptT, layer.wrap_prompt(prompt)) for prompt in layer.prefix_prompts)
- for slot in reversed(self.slots.values()):
- layer = slot.layer
- result.extend(cast(LayerPromptT, layer.wrap_prompt(prompt)) for prompt in layer.suffix_prompts)
- if self.prompt_transformer is None:
- return cast(list[PromptT], result)
- return list(self.prompt_transformer(result))
-
- @property
- def user_prompts(self) -> list[UserPromptT]:
- result: list[LayerUserPromptT] = []
- for slot in self.slots.values():
- layer = slot.layer
- result.extend(cast(LayerUserPromptT, layer.wrap_user_prompt(prompt)) for prompt in layer.user_prompts)
- if self.user_prompt_transformer is None:
- return cast(list[UserPromptT], result)
- return list(self.user_prompt_transformer(result))
-
- @property
- def tools(self) -> list[ToolT]:
- result: list[LayerToolT] = []
- for slot in self.slots.values():
- layer = slot.layer
- result.extend(cast(LayerToolT, layer.wrap_tool(tool)) for tool in layer.tools)
- if self.tool_transformer is None:
- return cast(list[ToolT], result)
- return list(self.tool_transformer(result))
diff --git a/dify-agent/src/agenton/compositor/schemas.py b/dify-agent/src/agenton/compositor/schemas.py
deleted file mode 100644
index 9bf7c7da922..00000000000
--- a/dify-agent/src/agenton/compositor/schemas.py
+++ /dev/null
@@ -1,115 +0,0 @@
-"""Serializable compositor DTOs and external boundary validation.
-
-Graph config and session snapshots are separate boundaries on purpose. Graph
-config describes only reusable composition state: schema version, ordered node
-names, provider type ids, dependency mappings, and metadata. Session snapshots
-carry only ordered layer lifecycle state plus serializable ``runtime_state``.
-Live resources acquired inside ``Layer.resource_context()`` are active-scope
-only and can never appear in these DTOs.
-
-External DTOs are revalidated even when callers pass an already-constructed
-Pydantic model instance. These models are mutable, so dumping and validating
-again prevents post-construction mutations from bypassing compositor entry
-validators. ``LifecycleState.ACTIVE`` remains internal-only and is rejected in
-external session snapshots.
-"""
-
-from collections.abc import Mapping
-
-from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator
-
-from agenton.layers.base import LifecycleState
-
-type _ConfigModelValue[ModelT: BaseModel] = ModelT | JsonValue | str | bytes
-
-
-def _validate_config_model_input[ModelT: BaseModel](
- model_type: type[ModelT],
- value: _ConfigModelValue[ModelT] | Mapping[str, object],
-) -> ModelT:
- """Validate an external DTO boundary, including existing model instances.
-
- Pydantic models in this package are generally mutable and do not all enable
- assignment validation. Revalidating existing instances through their dumped
- data prevents post-construction mutations from bypassing config or snapshot
- validators at compositor entry boundaries.
- """
- if isinstance(value, BaseModel):
- return model_type.model_validate(value.model_dump(mode="python", warnings=False))
- if isinstance(value, str | bytes):
- return model_type.model_validate_json(value)
-
- return model_type.model_validate(value)
-
-
-class LayerNodeConfig(BaseModel):
- """Serializable config for one provider-backed layer graph node.
-
- Nodes intentionally contain no runtime state and no per-call layer config.
- Runtime state belongs to session snapshots; layer config belongs to
- ``Compositor.enter(configs=...)`` keyed by node name.
- """
-
- name: str
- type: str
- deps: Mapping[str, str] = Field(default_factory=dict)
- metadata: Mapping[str, JsonValue] = Field(default_factory=dict)
-
- model_config = ConfigDict(extra="forbid")
-
-
-class CompositorConfig(BaseModel):
- """Serializable config for constructing a reusable compositor graph plan."""
-
- schema_version: int = 1
- layers: list[LayerNodeConfig]
-
- model_config = ConfigDict(extra="forbid")
-
-
-type CompositorConfigValue = _ConfigModelValue[CompositorConfig] | Mapping[str, object]
-
-
-def _validate_compositor_config_input(value: CompositorConfigValue) -> CompositorConfig:
- """Validate external graph config input for ``Compositor.from_config``."""
- return _validate_config_model_input(CompositorConfig, value)
-
-
-class LayerSessionSnapshot(BaseModel):
- """Serializable snapshot for one layer's state-only invocation data.
-
- ``runtime_state`` is the only snapshotted mutable layer data. ``ACTIVE`` is
- rejected here because a running layer cannot be represented safely outside
- the active compositor entry.
- """
-
- name: str
- lifecycle_state: LifecycleState
- runtime_state: dict[str, JsonValue]
-
- model_config = ConfigDict(extra="forbid")
-
- @field_validator("lifecycle_state")
- @classmethod
- def _reject_active_lifecycle(cls, value: LifecycleState) -> LifecycleState:
- if value is LifecycleState.ACTIVE:
- raise ValueError("LifecycleState.ACTIVE is internal-only and cannot appear in session snapshots.")
- return value
-
-
-class CompositorSessionSnapshot(BaseModel):
- """Serializable compositor session snapshot.
-
- Snapshots include ordered layer lifecycle state and serializable runtime
- state only. Live resources from ``Layer.resource_context()``, handles,
- dependencies, prompts, tools, and config are outside Agenton snapshots and
- are never captured here.
- """
-
- schema_version: int = 1
- layers: list[LayerSessionSnapshot]
-
- model_config = ConfigDict(extra="forbid")
-
-
-type CompositorSessionSnapshotValue = _ConfigModelValue[CompositorSessionSnapshot] | Mapping[str, object]
diff --git a/dify-agent/src/agenton/compositor/types.py b/dify-agent/src/agenton/compositor/types.py
deleted file mode 100644
index 984dc2014ea..00000000000
--- a/dify-agent/src/agenton/compositor/types.py
+++ /dev/null
@@ -1,46 +0,0 @@
-"""Shared generic compositor types.
-
-This module contains the generic prompt/tool type variables and transformer
-contracts shared by compositor runtime and orchestration modules. It depends
-only on layer base/types modules so higher-level compositor modules can import
-it without creating cycles.
-"""
-
-from collections.abc import Callable, Sequence
-from typing import Any, TypedDict
-
-from typing_extensions import TypeVar
-
-from agenton.layers.base import Layer
-from agenton.layers.types import AllPromptTypes, AllToolTypes, AllUserPromptTypes
-
-PromptT = TypeVar("PromptT", default=AllPromptTypes)
-ToolT = TypeVar("ToolT", default=AllToolTypes)
-LayerPromptT = TypeVar("LayerPromptT", default=AllPromptTypes)
-LayerToolT = TypeVar("LayerToolT", default=AllToolTypes)
-UserPromptT = TypeVar("UserPromptT", default=AllUserPromptTypes)
-LayerUserPromptT = TypeVar("LayerUserPromptT", default=AllUserPromptTypes)
-LayerT = TypeVar("LayerT", bound=Layer[Any, Any, Any, Any, Any, Any])
-
-
-type CompositorTransformer[InputT, OutputT] = Callable[[Sequence[InputT]], Sequence[OutputT]]
-
-
-class CompositorTransformerKwargs[
- PromptT,
- ToolT,
- LayerPromptT,
- LayerToolT,
- UserPromptT,
- LayerUserPromptT,
-](TypedDict):
- """Keyword arguments that install prompt, user prompt, and tool transformers.
-
- The required keys intentionally mirror the keyword-only transformer
- parameters exposed by ``Compositor.__init__`` and
- ``Compositor.from_config(...)``.
- """
-
- prompt_transformer: CompositorTransformer[LayerPromptT, PromptT]
- user_prompt_transformer: CompositorTransformer[LayerUserPromptT, UserPromptT]
- tool_transformer: CompositorTransformer[LayerToolT, ToolT]
diff --git a/dify-agent/src/agenton/layers/__init__.py b/dify-agent/src/agenton/layers/__init__.py
deleted file mode 100644
index bc02a13f0cb..00000000000
--- a/dify-agent/src/agenton/layers/__init__.py
+++ /dev/null
@@ -1,66 +0,0 @@
-"""Layer base classes and typed layer families.
-
-``agenton.layers.base`` owns the framework-neutral ``Layer`` abstraction.
-``agenton.layers.types`` binds the prompt/tool generic slots to specific layer
-families while keeping concrete reusable layers in ``agenton_collections``.
-"""
-
-from agenton.layers.base import (
- EmptyLayerConfig,
- EmptyRuntimeState,
- ExitIntent,
- Layer,
- LayerConfig,
- LayerConfigValue,
- LayerDeps,
- LifecycleState,
- NoLayerDeps,
-)
-from agenton.layers.types import (
- AllPromptTypes,
- AllToolTypes,
- AllUserPromptTypes,
- PlainLayer,
- PlainPrompt,
- PlainPromptType,
- PlainTool,
- PlainToolType,
- PlainUserPrompt,
- PlainUserPromptType,
- PydanticAILayer,
- PydanticAIPrompt,
- PydanticAIPromptType,
- PydanticAITool,
- PydanticAIToolType,
- PydanticAIUserPrompt,
- PydanticAIUserPromptType,
-)
-
-__all__ = [
- "AllPromptTypes",
- "AllToolTypes",
- "AllUserPromptTypes",
- "Layer",
- "LayerConfig",
- "LayerConfigValue",
- "LayerDeps",
- "LifecycleState",
- "ExitIntent",
- "EmptyLayerConfig",
- "EmptyRuntimeState",
- "NoLayerDeps",
- "PlainLayer",
- "PlainPrompt",
- "PlainPromptType",
- "PlainUserPrompt",
- "PlainUserPromptType",
- "PlainTool",
- "PlainToolType",
- "PydanticAILayer",
- "PydanticAIPrompt",
- "PydanticAIPromptType",
- "PydanticAIUserPrompt",
- "PydanticAIUserPromptType",
- "PydanticAITool",
- "PydanticAIToolType",
-]
diff --git a/dify-agent/src/agenton/layers/base.py b/dify-agent/src/agenton/layers/base.py
deleted file mode 100644
index d8f8035c1cd..00000000000
--- a/dify-agent/src/agenton/layers/base.py
+++ /dev/null
@@ -1,562 +0,0 @@
-"""Invocation-scoped core layer abstractions and typed dependency binding.
-
-Agenton core deliberately manages four concerns: stateless layer graph
-composition, serializable ``runtime_state`` lifecycle, per-active-invocation
-resource scopes, and session snapshots. Live resources remain layer-owned:
-Agenton may enter ``Layer.resource_context()`` for the active scope, but it
-never serializes or snapshots clients, process handles, cleanup stacks, or any
-other non-serializable runtime object.
-
-Layers declare their dependency shape with
-``Layer[DepsT, PromptT, UserPromptT, ToolT, ConfigT, RuntimeStateT]``.
-``DepsT`` must be a ``LayerDeps`` subclass whose annotated members are concrete
-``Layer`` subclasses or modern optional dependencies such as ``SomeLayer | None``.
-Dependencies are direct layer instance relationships bound onto ``self.deps``
-for one compositor invocation; there is no dependency-control lookup API in the
-core.
-
-``LayerConfig`` is the DTO base for config schemas accepted by layer providers.
-The provider validates raw node-name keyed configs with a layer's
-``config_type`` before constructing the layer and assigning ``self.config``.
-``runtime_state_type`` is the only mutable schema managed by Agenton and the only
-per-layer data included in session snapshots. The base class infers
-``deps_type``, ``config_type``, and ``runtime_state_type`` from generic bases
-when possible, while still allowing subclasses to set them explicitly for
-unusual inheritance patterns.
-
-``Layer`` is an invocation-scoped business object. It owns ``config``, direct
-``deps``, serializable ``runtime_state``, prompt/tool authoring surfaces, and
-any live resource fields managed by ``resource_context()``. It does not own
-lifecycle state, exit intent, graph owner tokens, or entry stacks.
-``CompositorRun`` owns lifecycle state and exit intent for one entry and
-orchestrates entering and exiting each layer's resource scope. ``SessionSnapshot``
-objects are the only supported cross-call state carrier.
-
-Lifecycle hooks are no-argument business hooks on the layer instance:
-``on_context_create/resume/suspend/delete(self)``. They should read dependencies
-from ``self.deps`` and read or mutate serializable invocation state through
-``self.runtime_state``. ``resource_context(self)`` is the symmetric active-scope
-API for live resources. Agenton enters it before ``on_context_create`` or
-``on_context_resume`` and exits it after ``on_context_suspend`` or
-``on_context_delete``. Create-versus-resume differences stay in the business
-hooks; ``resource_context`` should manage only live resource setup and cleanup.
-Agenton marks a slot ``ACTIVE`` only after ``on_context_create`` or
-``on_context_resume`` returns successfully. If either enter hook raises, normal
-``on_context_suspend``/``on_context_delete`` hooks do not run for that failed
-attempt. Enter hooks therefore own any business compensation or idempotency for
-partial side effects, while Agenton guarantees only ``resource_context()``
-cleanup, not hook rollback.
-
-``Layer`` is framework-neutral over system prompt, user prompt, and tool item
-types. The native ``prefix_prompts``, ``suffix_prompts``, ``user_prompts``, and
-``tools`` properties are the layer authoring surface. ``wrap_prompt``,
-``wrap_user_prompt``, and ``wrap_tool`` are the compositor aggregation surface;
-typed families such as ``agenton.layers.types.PlainLayer`` implement them to tag
-native values without changing layer implementations.
-"""
-
-from abc import ABC, abstractmethod
-from collections.abc import Mapping, Sequence
-from contextlib import asynccontextmanager
-from dataclasses import dataclass
-from enum import StrEnum
-from types import UnionType
-from typing import (
- Any,
- AsyncIterator,
- ClassVar,
- Generic,
- Union,
- cast,
- get_args,
- get_origin,
- get_type_hints,
-)
-
-from pydantic import BaseModel, ConfigDict, JsonValue, SerializeAsAny
-from typing_extensions import Self, TypeVar
-
-
-_DepsT = TypeVar("_DepsT", bound="LayerDeps")
-_PromptT = TypeVar("_PromptT")
-_UserPromptT = TypeVar("_UserPromptT")
-_ToolT = TypeVar("_ToolT")
-
-
-class LayerConfig(BaseModel):
- """Base DTO for serializable layer configuration.
-
- Layer providers validate raw config values with concrete ``LayerConfig``
- subclasses before constructing a layer for one invocation. Serializable
- compositor graph config references layer type ids and node metadata only;
- per-call config travels through ``Compositor.enter(configs=...)``.
- """
-
- model_config = ConfigDict(extra="forbid")
-
-
-type LayerConfigValue = JsonValue | SerializeAsAny[LayerConfig]
-
-
-_ConfigT = TypeVar("_ConfigT", bound=LayerConfig, default="EmptyLayerConfig")
-_RuntimeStateT = TypeVar("_RuntimeStateT", bound=BaseModel, default="EmptyRuntimeState")
-
-
-class LayerDeps:
- """Typed dependency container for a layer.
-
- Subclasses declare dependency members with annotations. Every annotated
- member must be a Layer subclass or ``LayerSubclass | None``. Optional deps
- are always assigned as attributes; missing optional values become ``None``.
- """
-
- def __init__(self, **deps: "Layer[Any, Any, Any, Any, Any, Any] | None") -> None:
- dep_specs = _get_dep_specs(type(self))
- missing_names = {name for name, spec in dep_specs.items() if not spec.optional} - deps.keys()
- if missing_names:
- names = ", ".join(sorted(missing_names))
- raise ValueError(f"Missing layer dependencies: {names}.")
-
- unknown_names = deps.keys() - dep_specs.keys()
- if unknown_names:
- names = ", ".join(sorted(unknown_names))
- raise ValueError(f"Unknown layer dependencies: {names}.")
-
- for name, spec in dep_specs.items():
- value = deps.get(name)
- if value is None:
- if spec.optional:
- setattr(self, name, None)
- continue
- raise ValueError(f"Dependency '{name}' is required but not provided.")
-
- if not isinstance(value, spec.layer_type):
- raise TypeError(
- f"Dependency '{name}' should be of type '{spec.layer_type.__name__}', "
- f"but got type '{type(value).__name__}'."
- )
- setattr(self, name, value)
-
-
-class NoLayerDeps(LayerDeps):
- """Dependency container for layers that do not require other layers."""
-
-
-class EmptyLayerConfig(LayerConfig):
- """Default serializable config schema for layers without config."""
-
- model_config = ConfigDict(extra="forbid")
-
-
-class EmptyRuntimeState(BaseModel):
- """Default serializable invocation runtime state schema."""
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-class LifecycleState(StrEnum):
- """Lifecycle state for one run slot.
-
- ``ACTIVE`` is internal-only. It is used while an invocation is running and
- must never appear in external session snapshots or hydrated input.
- """
-
- NEW = "new"
- ACTIVE = "active"
- SUSPENDED = "suspended"
- CLOSED = "closed"
-
-
-class ExitIntent(StrEnum):
- """Run-slot exit behavior requested during active invocation."""
-
- DELETE = "delete"
- SUSPEND = "suspend"
-
-
-@dataclass(frozen=True, slots=True)
-class LayerDepSpec:
- """Runtime dependency specification derived from a deps annotation."""
-
- layer_type: type["Layer[Any, Any, Any, Any, Any, Any]"]
- optional: bool = False
-
-
-class Layer(
- ABC,
- Generic[_DepsT, _PromptT, _UserPromptT, _ToolT, _ConfigT, _RuntimeStateT],
-):
- """Framework-neutral base class for prompt/tool layers.
-
- A layer instance is invocation-scoped mutable business state, not a reusable
- cross-session definition. ``CompositorRun`` creates fresh instances through
- layer providers, assigns validated ``config``, binds direct dependency layer
- instances to ``deps``, hydrates ``runtime_state`` from an optional session
- snapshot, and then runs no-argument lifecycle hooks. The run owns lifecycle
- state and exit intent; layers never expose a public entry context manager.
-
- ``runtime_state`` is the only mutable data Agenton snapshots across calls.
- Live resources belong on the layer instance itself and should be acquired in
- ``resource_context()``. Agenton keeps that resource scope active while the
- corresponding enter hook, run body, and exit hook execute, then tears it
- down deterministically even when later hooks or the body fail.
- """
-
- deps_type: type[_DepsT]
- config: _ConfigT
- deps: _DepsT
- runtime_state: _RuntimeStateT
- type_id: ClassVar[str | None] = None
- config_type: ClassVar[type[LayerConfig]] = EmptyLayerConfig
- runtime_state_type: ClassVar[type[BaseModel]] = EmptyRuntimeState
-
- def __new__(cls, *args: object, **kwargs: object) -> Self:
- instance = cast(Self, super().__new__(cls))
- runtime_state_type = getattr(cls, "runtime_state_type", None)
- if isinstance(runtime_state_type, type) and issubclass(runtime_state_type, BaseModel):
- instance.runtime_state = cast(Any, runtime_state_type.model_validate({}))
- return instance
-
- def __init_subclass__(cls) -> None:
- super().__init_subclass__()
- is_generic_template = _is_generic_layer_template(cls)
- deps_type = cls.__dict__.get("deps_type")
- if deps_type is None:
- deps_type = _infer_deps_type(cls) or getattr(cls, "deps_type", None)
- if deps_type is None and is_generic_template:
- return
- if deps_type is not None:
- cls.deps_type = cast(type[_DepsT], deps_type)
- if deps_type is None:
- raise TypeError(f"{cls.__name__} must define deps_type or inherit from Layer[DepsT].")
- if not isinstance(deps_type, type) or not issubclass(deps_type, LayerDeps):
- raise TypeError(f"{cls.__name__}.deps_type must be a LayerDeps subclass.")
- _get_dep_specs(deps_type)
- _init_config_type(cls, _infer_config_type(cls))
- _init_schema_type(
- cls,
- "runtime_state_type",
- _infer_schema_type(cls, 5, "runtime_state_type"),
- EmptyRuntimeState,
- )
-
- @classmethod
- def from_config(cls: type[Self], config: _ConfigT) -> Self:
- """Create a layer from schema-validated serialized config.
-
- ``LayerProvider.from_layer_type`` validates raw config with
- ``config_type`` before calling this method. Layers without config use the
- default no-argument construction path. Layers with a concrete config
- schema should override this method and consume the typed Pydantic model.
- """
- if cls.config_type is not EmptyLayerConfig:
- raise TypeError(f"{cls.__name__} cannot be created from config; override from_config or use a provider.")
- EmptyLayerConfig.model_validate(config)
- try:
- return cast(Self, cls())
- except TypeError as e:
- raise TypeError(f"{cls.__name__} cannot be created from empty config; use a custom provider.") from e
-
- @classmethod
- def dependency_names(cls) -> frozenset[str]:
- """Return dependency field names declared by this layer's deps schema."""
- return frozenset(_get_dep_specs(cls.deps_type))
-
- def bind_deps(self, deps: Mapping[str, "Layer[Any, Any, Any, Any, Any, Any] | None"]) -> None:
- """Bind this layer's declared dependencies from a name-to-layer mapping.
-
- The mapping may include more layers than the declared dependency fields.
- Only names declared by ``deps_type`` are selected and validated. Missing
- optional deps are bound as ``None``. Bound values are direct layer
- instances for this invocation graph.
- """
- resolved_deps: dict[str, Layer[Any, Any, Any, Any, Any, Any] | None] = {}
- for name, spec in _get_dep_specs(self.deps_type).items():
- if name not in deps:
- if spec.optional:
- resolved_deps[name] = None
- continue
- raise ValueError(f"Dependency '{name}' is required for layer '{type(self).__name__}' but not provided.")
- resolved_deps[name] = deps[name]
- self.deps = self.deps_type(**resolved_deps)
-
- @asynccontextmanager
- async def resource_context(self) -> AsyncIterator[None]:
- """Wrap one active invocation with live non-serializable resources.
-
- Agenton enters this no-argument context before ``on_context_create`` or
- ``on_context_resume`` and exits it after ``on_context_suspend`` or
- ``on_context_delete``. Use it for live clients, process handles, or
- other non-serializable objects stored on ``self``. Keep create-versus-
- resume business differences in the corresponding lifecycle hooks.
- """
- yield
-
- async def on_context_create(self) -> None:
- """Run when the run slot enters from ``LifecycleState.NEW``.
-
- ``resource_context()`` is already active for this layer when this hook
- runs. If this hook raises, the layer never becomes ``ACTIVE`` and no
- normal ``on_context_delete()`` hook runs for that failed enter attempt.
- """
-
- async def on_context_delete(self) -> None:
- """Run when the run slot exits with ``ExitIntent.DELETE``.
-
- ``resource_context()`` remains active while this hook runs.
- """
-
- async def on_context_suspend(self) -> None:
- """Run when the run slot exits with ``ExitIntent.SUSPEND``.
-
- ``resource_context()`` remains active while this hook runs.
- """
-
- async def on_context_resume(self) -> None:
- """Run when the run slot enters from ``LifecycleState.SUSPENDED``.
-
- ``resource_context()`` is already active for this layer when this hook
- runs. If this hook raises, the layer never becomes ``ACTIVE`` and no
- normal ``on_context_suspend()`` or ``on_context_delete()`` hook runs for
- that failed resume attempt.
- """
-
- @property
- def prefix_prompts(self) -> Sequence[_PromptT]:
- return []
-
- @property
- def suffix_prompts(self) -> Sequence[_PromptT]:
- return []
-
- @property
- def user_prompts(self) -> Sequence[_UserPromptT]:
- return []
-
- @property
- def tools(self) -> Sequence[_ToolT]:
- return []
-
- @abstractmethod
- def wrap_prompt(self, prompt: _PromptT) -> object:
- """Wrap a native prompt item for run-level aggregation."""
- raise NotImplementedError
-
- @abstractmethod
- def wrap_user_prompt(self, prompt: _UserPromptT) -> object:
- """Wrap a native user prompt item for run-level aggregation."""
- raise NotImplementedError
-
- @abstractmethod
- def wrap_tool(self, tool: _ToolT) -> object:
- """Wrap a native tool item for run-level aggregation."""
- raise NotImplementedError
-
-
-def _get_dep_specs(deps_type: type[LayerDeps]) -> dict[str, LayerDepSpec]:
- dep_specs: dict[str, LayerDepSpec] = {}
- for name, annotation in get_type_hints(deps_type).items():
- spec = _as_dep_spec(annotation)
- if spec is None:
- raise TypeError(
- f"{deps_type.__name__}.{name} must be annotated with a Layer subclass or Layer subclass | None."
- )
- dep_specs[name] = spec
- return dep_specs
-
-
-def _as_dep_spec(annotation: object) -> LayerDepSpec | None:
- origin = get_origin(annotation)
- args = get_args(annotation)
- if origin in (UnionType, Union) and len(args) == 2 and type(None) in args:
- layer_annotation = args[0] if args[1] is type(None) else args[1]
- layer_type = _as_layer_type(layer_annotation)
- if layer_type is None:
- return None
- return LayerDepSpec(layer_type=layer_type, optional=True)
-
- layer_type = _as_layer_type(annotation)
- if layer_type is None:
- return None
- return LayerDepSpec(layer_type=layer_type)
-
-
-def _as_layer_type(annotation: object) -> type[Layer[Any, Any, Any, Any, Any, Any]] | None:
- runtime_type = get_origin(annotation) or annotation
- if isinstance(runtime_type, type) and issubclass(runtime_type, Layer):
- return cast(type[Layer[Any, Any, Any, Any, Any, Any]], runtime_type)
- return None
-
-
-def _infer_deps_type(layer_type: type[Layer[Any, Any, Any, Any, Any, Any]]) -> type[LayerDeps] | None:
- inferred = _infer_layer_generic_arg(layer_type, 0, {})
- if inferred is None:
- return None
- return _as_deps_type(inferred)
-
-
-def _infer_schema_type(
- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],
- index: int,
- attr_name: str,
-) -> type[BaseModel] | None:
- inferred = _infer_schema_generic_arg(layer_type, attr_name, {}) or _infer_layer_generic_arg(layer_type, index, {})
- if inferred is None:
- return None
- schema_type = _as_model_type(inferred)
- if schema_type is None:
- raise TypeError(f"{layer_type.__name__}.{attr_name} must be a Pydantic BaseModel subclass.")
- return schema_type
-
-
-def _infer_config_type(layer_type: type[Layer[Any, Any, Any, Any, Any, Any]]) -> type[LayerConfig] | None:
- inferred = _infer_schema_generic_arg(layer_type, "config_type", {}) or _infer_layer_generic_arg(layer_type, 4, {})
- if inferred is None:
- return None
- config_type = _as_config_type(inferred)
- if config_type is None:
- raise TypeError(f"{layer_type.__name__}.config_type must be a LayerConfig subclass.")
- return config_type
-
-
-def _infer_schema_generic_arg(
- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],
- attr_name: str,
- substitutions: Mapping[object, object],
-) -> object | None:
- """Infer schema type arguments exposed by typed layer family bases."""
- expected_names = {
- "config_type": {"ConfigT", "_ConfigT"},
- "runtime_state_type": {"RuntimeStateT", "_RuntimeStateT"},
- }[attr_name]
- for base in getattr(layer_type, "__orig_bases__", ()):
- origin = get_origin(base) or base
- args = tuple(_substitute_type(arg, substitutions) for arg in get_args(base))
- if not isinstance(origin, type) or not issubclass(origin, Layer):
- continue
-
- params = _generic_params(origin)
- for param, arg in zip(params, args):
- if getattr(param, "__name__", None) in expected_names:
- return arg
-
- next_substitutions = dict(substitutions)
- next_substitutions.update(_generic_arg_substitutions(origin, args))
- inferred = _infer_schema_generic_arg(origin, attr_name, next_substitutions)
- if inferred is not None:
- return inferred
- return None
-
-
-def _infer_layer_generic_arg(
- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],
- index: int,
- substitutions: Mapping[object, object],
-) -> object | None:
- """Infer one concrete ``Layer`` generic argument through inheritance.
-
- This walks through intermediate generic base classes so subclasses can omit
- explicit class attributes in common cases such as ``class X(Base[YDeps])``.
- """
- for base in getattr(layer_type, "__orig_bases__", ()):
- origin = get_origin(base) or base
- args = tuple(_substitute_type(arg, substitutions) for arg in get_args(base))
- if origin is Layer:
- if len(args) <= index:
- continue
- return args[index]
-
- if not isinstance(origin, type) or not issubclass(origin, Layer):
- continue
-
- next_substitutions = dict(substitutions)
- next_substitutions.update(_generic_arg_substitutions(origin, args))
- inferred = _infer_layer_generic_arg(origin, index, next_substitutions)
- if inferred is not None:
- return inferred
- return None
-
-
-def _init_schema_type(
- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],
- attr_name: str,
- inferred_schema_type: type[BaseModel] | None,
- default_schema_type: type[BaseModel],
-) -> None:
- schema_type = layer_type.__dict__.get(attr_name)
- if schema_type is None:
- schema_type = inferred_schema_type or getattr(layer_type, attr_name, default_schema_type)
- setattr(layer_type, attr_name, schema_type)
- if not isinstance(schema_type, type) or not issubclass(schema_type, BaseModel):
- raise TypeError(f"{layer_type.__name__}.{attr_name} must be a Pydantic BaseModel subclass.")
-
-
-def _init_config_type(
- layer_type: type[Layer[Any, Any, Any, Any, Any, Any]],
- inferred_config_type: type[LayerConfig] | None,
-) -> None:
- config_type = layer_type.__dict__.get("config_type")
- if config_type is None:
- config_type = inferred_config_type or getattr(layer_type, "config_type", EmptyLayerConfig)
- setattr(layer_type, "config_type", config_type)
- if not isinstance(config_type, type) or not issubclass(config_type, LayerConfig):
- raise TypeError(f"{layer_type.__name__}.config_type must be a LayerConfig subclass.")
-
-
-def _substitute_type(value: object, substitutions: Mapping[object, object]) -> object:
- if value in substitutions:
- return substitutions[value]
-
- origin = get_origin(value)
- if origin is None:
- return value
-
- args = get_args(value)
- if not args:
- return value
-
- substituted_args = tuple(_substitute_type(arg, substitutions) for arg in args)
- if substituted_args == args:
- return value
-
- try:
- return origin[substituted_args]
- except TypeError:
- return value
-
-
-def _generic_arg_substitutions(origin: type[Any], args: Sequence[object]) -> dict[object, object]:
- params = _generic_params(origin)
- return dict(zip(params, args))
-
-
-def _generic_params(origin: type[Any]) -> Sequence[object]:
- params = getattr(origin, "__type_params__", ())
- if not params:
- params = getattr(origin, "__parameters__", ())
- return params
-
-
-def _as_deps_type(value: object) -> type[LayerDeps] | None:
- runtime_type = get_origin(value) or value
- if isinstance(runtime_type, type) and issubclass(runtime_type, LayerDeps):
- return runtime_type
- return None
-
-
-def _as_model_type(value: object) -> type[BaseModel] | None:
- runtime_type = get_origin(value) or value
- if isinstance(runtime_type, type) and issubclass(runtime_type, BaseModel):
- return runtime_type
- return None
-
-
-def _as_config_type(value: object) -> type[LayerConfig] | None:
- runtime_type = get_origin(value) or value
- if isinstance(runtime_type, type) and issubclass(runtime_type, LayerConfig):
- return runtime_type
- return None
-
-
-def _is_generic_layer_template(layer_type: type[Layer[Any, Any, Any, Any, Any, Any]]) -> bool:
- return bool(getattr(layer_type, "__type_params__", ())) or bool(getattr(layer_type, "__parameters__", ()))
diff --git a/dify-agent/src/agenton/layers/types.py b/dify-agent/src/agenton/layers/types.py
deleted file mode 100644
index e6133dcd55f..00000000000
--- a/dify-agent/src/agenton/layers/types.py
+++ /dev/null
@@ -1,184 +0,0 @@
-"""Typed layer family definitions.
-
-``Layer`` itself is framework-neutral. This module defines typed layer families
-that bind its system prompt, user prompt, and tool generic slots to concrete
-contracts, such as ordinary strings with plain callable tools or pydantic-ai
-prompt/tool shapes. The families keep the trailing schema generic slots open so
-concrete layers can have ``config_type`` and ``runtime_state_type`` inferred from
-type arguments instead of repeated class attributes. Config schemas use
-``LayerConfig`` so they can also be embedded as
-typed DTOs in serializable compositor config. Agenton core is state-only:
-typed layer families do not expose runtime handle schemas or resource ownership.
-Tagged aggregate aliases cover code paths that can accept any supported
-prompt/tool family without changing the plain and pydantic-ai layer contracts.
-Pydantic-ai names are imported for static analysis only, so ``agenton`` can be
-imported without loading that optional integration at runtime.
-Concrete reusable layers live under ``agenton_collections``.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Generic, Literal
-
-from typing_extensions import TypeVar, final, override
-
-if TYPE_CHECKING:
- from pydantic_ai import Tool
- from pydantic_ai.messages import UserContent
- from pydantic_ai.tools import SystemPromptFunc
-
-from pydantic import BaseModel
-
-from agenton.layers.base import EmptyLayerConfig, EmptyRuntimeState, Layer, LayerConfig, LayerDeps
-
-type PlainPrompt = str
-type PlainUserPrompt = str
-type PlainTool = Callable[..., Any]
-
-
-type PydanticAIPrompt[AgentDepsT] = SystemPromptFunc[AgentDepsT]
-type PydanticAIUserPrompt = UserContent
-type PydanticAITool[AgentDepsT] = Tool[AgentDepsT]
-
-
-@dataclass(frozen=True, slots=True)
-class PlainPromptType:
- """Tagged plain prompt item for aggregate prompt transformations."""
-
- value: PlainPrompt
- kind: Literal["plain"] = field(default="plain", init=False)
-
-
-@dataclass(frozen=True, slots=True)
-class PlainToolType:
- """Tagged plain tool item for aggregate tool transformations."""
-
- value: PlainTool
- kind: Literal["plain"] = field(default="plain", init=False)
-
-
-@dataclass(frozen=True, slots=True)
-class PlainUserPromptType:
- """Tagged plain user prompt item for aggregate user prompt transformations."""
-
- value: PlainUserPrompt
- kind: Literal["plain"] = field(default="plain", init=False)
-
-
-@dataclass(frozen=True, slots=True)
-class PydanticAIPromptType[AgentDepsT]:
- """Tagged pydantic-ai prompt item for aggregate prompt transformations."""
-
- value: PydanticAIPrompt[AgentDepsT]
- kind: Literal["pydantic_ai"] = field(default="pydantic_ai", init=False)
-
-
-@dataclass(frozen=True, slots=True)
-class PydanticAIUserPromptType:
- """Tagged pydantic-ai user prompt item for aggregate user prompts."""
-
- value: PydanticAIUserPrompt
- kind: Literal["pydantic_ai"] = field(default="pydantic_ai", init=False)
-
-
-@dataclass(frozen=True, slots=True)
-class PydanticAIToolType[AgentDepsT]:
- """Tagged pydantic-ai tool item for aggregate tool transformations."""
-
- value: PydanticAITool[AgentDepsT]
- kind: Literal["pydantic_ai"] = field(default="pydantic_ai", init=False)
-
-
-type AllPromptTypes = PlainPromptType | PydanticAIPromptType[Any]
-type AllUserPromptTypes = PlainUserPromptType | PydanticAIUserPromptType
-type AllToolTypes = PlainToolType | PydanticAIToolType[Any]
-
-
-_DepsT = TypeVar("_DepsT", bound=LayerDeps)
-_ConfigT = TypeVar("_ConfigT", bound=LayerConfig, default=EmptyLayerConfig)
-_RuntimeStateT = TypeVar("_RuntimeStateT", bound=BaseModel, default=EmptyRuntimeState)
-_AgentDepsT = TypeVar("_AgentDepsT")
-
-
-class PlainLayer(
- Generic[_DepsT, _ConfigT, _RuntimeStateT],
- Layer[
- _DepsT,
- PlainPrompt,
- PlainUserPrompt,
- PlainTool,
- _ConfigT,
- _RuntimeStateT,
- ],
-):
- """Layer base for ordinary string prompts and plain-callable tools."""
-
- @final
- @override
- def wrap_prompt(self, prompt: PlainPrompt) -> PlainPromptType:
- return PlainPromptType(prompt)
-
- @final
- @override
- def wrap_user_prompt(self, prompt: PlainUserPrompt) -> PlainUserPromptType:
- return PlainUserPromptType(prompt)
-
- @final
- @override
- def wrap_tool(self, tool: PlainTool) -> PlainToolType:
- return PlainToolType(tool)
-
-
-class PydanticAILayer(
- Generic[_DepsT, _AgentDepsT, _ConfigT, _RuntimeStateT],
- Layer[
- _DepsT,
- PydanticAIPrompt[_AgentDepsT],
- PydanticAIUserPrompt,
- PydanticAITool[_AgentDepsT],
- _ConfigT,
- _RuntimeStateT,
- ],
-):
- """Layer base for pydantic-ai prompt and tool adapters."""
-
- @final
- @override
- def wrap_prompt(
- self,
- prompt: PydanticAIPrompt[_AgentDepsT],
- ) -> PydanticAIPromptType[_AgentDepsT]:
- return PydanticAIPromptType(prompt)
-
- @final
- @override
- def wrap_user_prompt(self, prompt: PydanticAIUserPrompt) -> PydanticAIUserPromptType:
- return PydanticAIUserPromptType(prompt)
-
- @final
- @override
- def wrap_tool(self, tool: PydanticAITool[_AgentDepsT]) -> PydanticAIToolType[_AgentDepsT]:
- return PydanticAIToolType(tool)
-
-
-__all__ = [
- "AllPromptTypes",
- "AllUserPromptTypes",
- "AllToolTypes",
- "PlainLayer",
- "PlainPrompt",
- "PlainPromptType",
- "PlainUserPrompt",
- "PlainUserPromptType",
- "PlainTool",
- "PlainToolType",
- "PydanticAILayer",
- "PydanticAIPrompt",
- "PydanticAIPromptType",
- "PydanticAIUserPrompt",
- "PydanticAIUserPromptType",
- "PydanticAITool",
- "PydanticAIToolType",
-]
diff --git a/dify-agent/src/agenton_collections/__init__.py b/dify-agent/src/agenton_collections/__init__.py
deleted file mode 100644
index b4b52de993b..00000000000
--- a/dify-agent/src/agenton_collections/__init__.py
+++ /dev/null
@@ -1,52 +0,0 @@
-"""Convenience exports for reusable layer implementations.
-
-Concrete collection layers live in family subpackages such as
-``agenton_collections.layers.plain`` and
-``agenton_collections.layers.pydantic_ai``. The package root keeps short
-client-safe imports for common plain layers while requiring explicit submodule
-imports for pydantic-ai bridge implementations.
-"""
-
-from agenton.layers.types import (
- AllPromptTypes,
- AllToolTypes,
- PlainLayer,
- PlainPrompt,
- PlainPromptType,
- PlainTool,
- PlainToolType,
- PydanticAILayer,
- PydanticAIPrompt,
- PydanticAIPromptType,
- PydanticAITool,
- PydanticAIToolType,
-)
-from agenton_collections.layers.plain import (
- DynamicToolsLayer,
- DynamicToolsLayerDeps,
- ObjectLayer,
- PromptLayer,
- ToolsLayer,
- with_object,
-)
-
-__all__ = [
- "AllPromptTypes",
- "AllToolTypes",
- "DynamicToolsLayer",
- "DynamicToolsLayerDeps",
- "ObjectLayer",
- "PlainLayer",
- "PlainPrompt",
- "PlainPromptType",
- "PlainTool",
- "PlainToolType",
- "PromptLayer",
- "PydanticAILayer",
- "PydanticAIPrompt",
- "PydanticAIPromptType",
- "PydanticAITool",
- "PydanticAIToolType",
- "ToolsLayer",
- "with_object",
-]
diff --git a/dify-agent/src/agenton_collections/layers/plain/__init__.py b/dify-agent/src/agenton_collections/layers/plain/__init__.py
deleted file mode 100644
index a3e20cc204f..00000000000
--- a/dify-agent/src/agenton_collections/layers/plain/__init__.py
+++ /dev/null
@@ -1,25 +0,0 @@
-"""Reusable collection layers for the plain layer family."""
-
-from agenton_collections.layers.plain.basic import (
- PLAIN_PROMPT_LAYER_TYPE_ID,
- ObjectLayer,
- PromptLayer,
- PromptLayerConfig,
- ToolsLayer,
-)
-from agenton_collections.layers.plain.dynamic_tools import (
- DynamicToolsLayer,
- DynamicToolsLayerDeps,
- with_object,
-)
-
-__all__ = [
- "DynamicToolsLayer",
- "DynamicToolsLayerDeps",
- "ObjectLayer",
- "PLAIN_PROMPT_LAYER_TYPE_ID",
- "PromptLayer",
- "PromptLayerConfig",
- "ToolsLayer",
- "with_object",
-]
diff --git a/dify-agent/src/agenton_collections/layers/plain/basic.py b/dify-agent/src/agenton_collections/layers/plain/basic.py
deleted file mode 100644
index aeefd1abf8f..00000000000
--- a/dify-agent/src/agenton_collections/layers/plain/basic.py
+++ /dev/null
@@ -1,103 +0,0 @@
-"""Basic ready-to-compose layers for common plain use cases.
-
-These layers are small concrete implementations built on
-``agenton.layers.types``. They intentionally stay free of compositor graph
-construction so they can be reused from config, examples, and higher-level
-dynamic layers.
-"""
-
-from collections.abc import Callable, Sequence
-from dataclasses import dataclass, field
-from typing import Any, Final
-
-from pydantic import ConfigDict, Field
-from typing_extensions import Self, override
-
-from agenton.layers.base import LayerConfig, NoLayerDeps
-from agenton.layers.types import PlainLayer
-
-
-PLAIN_PROMPT_LAYER_TYPE_ID: Final[str] = "plain.prompt"
-
-
-class PromptLayerConfig(LayerConfig):
- """Serializable config schema for ``PromptLayer``."""
-
- prefix: list[str] | str = Field(default_factory=list)
- user: list[str] | str = Field(default_factory=list)
- suffix: list[str] | str = Field(default_factory=list)
-
- model_config = ConfigDict(extra="forbid")
-
-
-@dataclass
-class ObjectLayer[ObjectT](PlainLayer[NoLayerDeps]):
- """Layer that stores one typed object for downstream dependencies.
-
- Object layers are instance-only because arbitrary Python objects are not
- serializable graph config. Add them with a custom ``LayerProvider`` factory
- that creates a fresh object layer for each compositor run.
- """
-
- value: ObjectT
-
-
-@dataclass
-class PromptLayer(PlainLayer[NoLayerDeps, PromptLayerConfig]):
- """Layer that contributes configured system and user prompt fragments."""
-
- type_id = PLAIN_PROMPT_LAYER_TYPE_ID
-
- prefix: list[str] | str = field(default_factory=list)
- user: list[str] | str = field(default_factory=list)
- suffix: list[str] | str = field(default_factory=list)
-
- @classmethod
- @override
- def from_config(cls, config: PromptLayerConfig) -> Self:
- """Create a prompt layer from validated prompt config."""
- validated_config = PromptLayerConfig.model_validate(config)
- return cls(prefix=validated_config.prefix, user=validated_config.user, suffix=validated_config.suffix)
-
- @property
- def prefix_prompts(self) -> list[str]:
- if isinstance(self.prefix, str):
- return [self.prefix]
- return self.prefix
-
- @property
- def suffix_prompts(self) -> list[str]:
- if isinstance(self.suffix, str):
- return [self.suffix]
- return self.suffix
-
- @property
- def user_prompts(self) -> list[str]:
- if isinstance(self.user, str):
- return [self.user]
- return self.user
-
-
-@dataclass
-class ToolsLayer(PlainLayer[NoLayerDeps]):
- """Layer that contributes configured plain-callable tools.
-
- Tool layers are instance-only because Python callables are live objects. Add
- them with a custom ``LayerProvider`` factory that returns a fresh layer for
- each compositor run.
- """
-
- tool_entries: Sequence[Callable[..., Any]] = ()
-
- @property
- def tools(self) -> list[Callable[..., Any]]:
- return list(self.tool_entries)
-
-
-__all__ = [
- "ObjectLayer",
- "PLAIN_PROMPT_LAYER_TYPE_ID",
- "PromptLayerConfig",
- "PromptLayer",
- "ToolsLayer",
-]
diff --git a/dify-agent/src/agenton_collections/layers/plain/dynamic_tools.py b/dify-agent/src/agenton_collections/layers/plain/dynamic_tools.py
deleted file mode 100644
index 12c78990a35..00000000000
--- a/dify-agent/src/agenton_collections/layers/plain/dynamic_tools.py
+++ /dev/null
@@ -1,232 +0,0 @@
-"""Dynamic plain-tool layer with object-bound tool entries.
-
-This module builds on ``ObjectLayer`` from ``agenton_collections.plain.basic``.
-Plain callables are exposed unchanged, while entries wrapped with
-``with_object`` bind the current object value into the first callable argument
-and expose the remaining parameters as the public tool signature.
-"""
-
-from collections.abc import Callable, Sequence
-from dataclasses import dataclass
-from functools import wraps
-from inspect import Parameter, Signature, iscoroutinefunction, signature
-from types import UnionType
-from typing import (
- Annotated,
- Any,
- Concatenate,
- Union,
- get_args,
- get_origin,
- get_type_hints,
-)
-
-from agenton.layers.base import LayerDeps
-from agenton.layers.types import PlainLayer
-from agenton_collections.layers.plain.basic import ObjectLayer
-
-type _ObjectToolCallable[ObjectT] = Callable[Concatenate[ObjectT, ...], Any]
-
-
-@dataclass(frozen=True, slots=True)
-class _ObjectToolEntry[ObjectT]:
- """Tool entry whose first argument should be filled from ``ObjectLayer``."""
-
- tool_entry: _ObjectToolCallable[ObjectT]
- object_type: type[ObjectT] | None = None
-
-
-type _DynamicToolEntry[ObjectT] = Callable[..., Any] | _ObjectToolEntry[ObjectT]
-
-
-def with_object[ObjectT](
- object_type: type[ObjectT],
- /,
-) -> Callable[[_ObjectToolCallable[ObjectT]], _ObjectToolEntry[ObjectT]]:
- """Mark a tool as requiring the bound object value as its first argument."""
-
- def decorator(tool_entry: _ObjectToolCallable[ObjectT]) -> _ObjectToolEntry[ObjectT]:
- _validate_object_tool_annotation(tool_entry, object_type)
- return _ObjectToolEntry(tool_entry=tool_entry, object_type=object_type)
-
- return decorator
-
-
-class DynamicToolsLayerDeps[ObjectT](LayerDeps):
- """Dependencies required by ``DynamicToolsLayer``."""
-
- object_layer: ObjectLayer[ObjectT] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass
-class DynamicToolsLayer[ObjectT](PlainLayer[DynamicToolsLayerDeps[ObjectT]]):
- """Layer that exposes plain tools and object-bound tools."""
-
- tool_entries: Sequence[_DynamicToolEntry[ObjectT]] = ()
-
- @property
- def tools(self) -> list[Callable[..., Any]]:
- object_value = self.deps.object_layer.value
- return [
- _bind_object_argument(tool_entry.tool_entry, object_value, tool_entry.object_type)
- if isinstance(tool_entry, _ObjectToolEntry)
- else tool_entry
- for tool_entry in self.tool_entries
- ]
-
-
-def _bind_object_argument[ObjectT](
- tool_entry: _ObjectToolCallable[ObjectT],
- object_value: ObjectT,
- object_type: type[ObjectT] | None,
-) -> Callable[..., Any]:
- _validate_object_value(tool_entry, object_value, object_type)
- if iscoroutinefunction(tool_entry):
- wrapped = _async_object_wrapper(tool_entry, object_value)
- else:
- wrapped = _sync_object_wrapper(tool_entry, object_value)
-
- public_signature = _public_tool_signature(tool_entry)
- if public_signature is not None:
- setattr(wrapped, "__signature__", public_signature)
- _set_public_annotations(wrapped, tool_entry)
- return wrapped
-
-
-def _validate_object_tool_annotation[ObjectT](
- tool_entry: _ObjectToolCallable[ObjectT],
- object_type: type[ObjectT],
-) -> None:
- parameter = _first_object_parameter(tool_entry)
- if parameter is None:
- return
-
- annotation = _parameter_annotation(tool_entry, parameter)
- if annotation is Parameter.empty:
- return
- if _annotation_accepts_object_type(annotation, object_type):
- return
-
- raise TypeError(
- f"Object-bound tool '{_tool_name(tool_entry)}' first parameter should accept '{_type_name(object_type)}'."
- )
-
-
-def _first_object_parameter(tool_entry: Callable[..., Any]) -> Parameter | None:
- try:
- tool_signature = signature(tool_entry)
- except (TypeError, ValueError):
- return None
-
- parameters = list(tool_signature.parameters.values())
- if not parameters:
- raise ValueError("Dynamic tools must accept the object dependency as their first parameter.")
- return parameters[0]
-
-
-def _parameter_annotation(tool_entry: Callable[..., Any], parameter: Parameter) -> object:
- try:
- type_hints = get_type_hints(tool_entry, include_extras=True)
- except (AttributeError, NameError, TypeError):
- return parameter.annotation
- return type_hints.get(parameter.name, parameter.annotation)
-
-
-def _annotation_accepts_object_type(annotation: object, object_type: type[Any]) -> bool:
- if annotation is Any or annotation is Parameter.empty:
- return True
-
- origin = get_origin(annotation)
- if origin is Annotated:
- args = get_args(annotation)
- return True if not args else _annotation_accepts_object_type(args[0], object_type)
- if origin in (UnionType, Union):
- return any(
- arg is type(None) or _annotation_accepts_object_type(arg, object_type) for arg in get_args(annotation)
- )
-
- runtime_type = origin or annotation
- if not isinstance(runtime_type, type):
- return True
- try:
- return issubclass(object_type, runtime_type)
- except TypeError:
- return True
-
-
-def _validate_object_value[ObjectT](
- tool_entry: _ObjectToolCallable[ObjectT],
- object_value: ObjectT,
- object_type: type[ObjectT] | None,
-) -> None:
- if object_type is None or isinstance(object_value, object_type):
- return
- raise TypeError(
- f"Object-bound tool '{_tool_name(tool_entry)}' expected object dependency "
- f"of type '{_type_name(object_type)}', but got '{type(object_value).__qualname__}'."
- )
-
-
-def _tool_name(tool_entry: Callable[..., Any]) -> str:
- return getattr(tool_entry, "__qualname__", getattr(tool_entry, "__name__", repr(tool_entry)))
-
-
-def _type_name(object_type: type[Any]) -> str:
- return object_type.__qualname__
-
-
-def _sync_object_wrapper[ObjectT](
- tool_entry: _ObjectToolCallable[ObjectT],
- object_value: ObjectT,
-) -> Callable[..., Any]:
- @wraps(tool_entry)
- def wrapped(*args: Any, **kwargs: Any) -> Any:
- return tool_entry(object_value, *args, **kwargs)
-
- return wrapped
-
-
-def _async_object_wrapper[ObjectT](
- tool_entry: _ObjectToolCallable[ObjectT],
- object_value: ObjectT,
-) -> Callable[..., Any]:
- @wraps(tool_entry)
- async def wrapped(*args: Any, **kwargs: Any) -> Any:
- return await tool_entry(object_value, *args, **kwargs)
-
- return wrapped
-
-
-def _public_tool_signature(tool_entry: Callable[..., Any]) -> Signature | None:
- try:
- tool_signature = signature(tool_entry)
- except (TypeError, ValueError):
- return None
-
- parameters = list(tool_signature.parameters.values())
- if not parameters:
- raise ValueError("Dynamic tools must accept the object dependency as their first parameter.")
- return tool_signature.replace(parameters=parameters[1:])
-
-
-def _set_public_annotations(wrapper: Callable[..., Any], tool_entry: Callable[..., Any]) -> None:
- annotations = getattr(tool_entry, "__annotations__", None)
- if not isinstance(annotations, dict):
- return
-
- try:
- parameters = list(signature(tool_entry).parameters)
- except (TypeError, ValueError):
- parameters = []
-
- public_annotations = dict(annotations)
- if parameters:
- public_annotations.pop(parameters[0], None)
- wrapper.__annotations__ = public_annotations
-
-
-__all__ = [
- "DynamicToolsLayer",
- "DynamicToolsLayerDeps",
- "with_object",
-]
diff --git a/dify-agent/src/agenton_collections/layers/pydantic_ai/__init__.py b/dify-agent/src/agenton_collections/layers/pydantic_ai/__init__.py
deleted file mode 100644
index 67f8869d0fd..00000000000
--- a/dify-agent/src/agenton_collections/layers/pydantic_ai/__init__.py
+++ /dev/null
@@ -1,19 +0,0 @@
-"""Reusable collection layers for the pydantic-ai layer family."""
-
-from agenton_collections.layers.pydantic_ai.bridge import (
- PydanticAIBridgeLayer,
- PydanticAIBridgeLayerDeps,
-)
-from agenton_collections.layers.pydantic_ai.history import (
- PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- PydanticAIHistoryLayer,
- PydanticAIHistoryRuntimeState,
-)
-
-__all__ = [
- "PydanticAIBridgeLayer",
- "PydanticAIBridgeLayerDeps",
- "PYDANTIC_AI_HISTORY_LAYER_TYPE_ID",
- "PydanticAIHistoryLayer",
- "PydanticAIHistoryRuntimeState",
-]
diff --git a/dify-agent/src/agenton_collections/layers/pydantic_ai/bridge.py b/dify-agent/src/agenton_collections/layers/pydantic_ai/bridge.py
deleted file mode 100644
index c2f9c668db2..00000000000
--- a/dify-agent/src/agenton_collections/layers/pydantic_ai/bridge.py
+++ /dev/null
@@ -1,106 +0,0 @@
-"""Pydantic AI bridge prompt and tool layer.
-
-This module keeps pydantic-ai's callable shapes intact through
-``PydanticAILayer``. The bridge layer depends on ``ObjectLayer`` so callers have
-one explicit graph node that provides the object used as
-``RunContext[ObjectT].deps`` in pydantic-ai prompt and tool callables.
-Bridge construction accepts pydantic-ai's ergonomic input forms and normalizes
-them at the layer boundary: string system prompts become zero-arg system prompt
-functions, user prompts stay as pydantic-ai ``UserContent`` values, and bare
-tool functions become ``Tool`` instances.
-"""
-
-from collections.abc import Sequence
-from dataclasses import dataclass
-
-from pydantic_ai import Tool
-from pydantic_ai.messages import UserContent
-from pydantic_ai.tools import ToolFuncEither
-from typing_extensions import override
-
-from agenton.layers.base import LayerDeps
-from agenton.layers.types import PydanticAILayer, PydanticAIPrompt, PydanticAITool, PydanticAIUserPrompt
-from agenton_collections.layers.plain.basic import ObjectLayer
-
-
-class PydanticAIBridgeLayerDeps[ObjectT](LayerDeps):
- """Dependencies required by ``PydanticAIBridgeLayer``."""
-
- object_layer: ObjectLayer[ObjectT] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass
-class PydanticAIBridgeLayer[ObjectT](PydanticAILayer[PydanticAIBridgeLayerDeps[ObjectT], ObjectT]):
- """Bridge layer for pydantic-ai prompts and tools using one object deps."""
-
- prefix: str | PydanticAIPrompt[ObjectT] | Sequence[str | PydanticAIPrompt[ObjectT]] = ()
- user: UserContent | Sequence[UserContent] = ()
- suffix: str | PydanticAIPrompt[ObjectT] | Sequence[str | PydanticAIPrompt[ObjectT]] = ()
- tool_entries: Sequence[PydanticAITool[ObjectT] | ToolFuncEither[ObjectT, ...]] = ()
-
- @property
- def run_deps(self) -> ObjectT:
- """Object to pass as pydantic-ai run deps for this layer."""
- return self.deps.object_layer.value
-
- @property
- @override
- def prefix_prompts(self) -> list[PydanticAIPrompt[ObjectT]]:
- return _normalize_prompts(self.prefix)
-
- @property
- @override
- def suffix_prompts(self) -> list[PydanticAIPrompt[ObjectT]]:
- return _normalize_prompts(self.suffix)
-
- @property
- @override
- def user_prompts(self) -> list[PydanticAIUserPrompt]:
- return _normalize_user_prompts(self.user)
-
- @property
- @override
- def tools(self) -> list[PydanticAITool[ObjectT]]:
- return [_normalize_tool(tool_entry) for tool_entry in self.tool_entries]
-
-
-def _normalize_prompts[ObjectT](
- prompts: str | PydanticAIPrompt[ObjectT] | Sequence[str | PydanticAIPrompt[ObjectT]],
-) -> list[PydanticAIPrompt[ObjectT]]:
- if isinstance(prompts, str):
- return [_normalize_prompt(prompts)]
- if isinstance(prompts, Sequence):
- return [_normalize_prompt(prompt) for prompt in prompts]
- return [prompts]
-
-
-def _normalize_prompt[ObjectT](
- prompt: str | PydanticAIPrompt[ObjectT],
-) -> PydanticAIPrompt[ObjectT]:
- if isinstance(prompt, str):
- return (lambda value: lambda: value)(prompt)
- return prompt
-
-
-def _normalize_user_prompts(
- prompts: UserContent | Sequence[UserContent],
-) -> list[PydanticAIUserPrompt]:
- if isinstance(prompts, str):
- return [prompts]
- if isinstance(prompts, Sequence):
- return list(prompts)
- return [prompts]
-
-
-def _normalize_tool[ObjectT](
- tool_entry: PydanticAITool[ObjectT] | ToolFuncEither[ObjectT, ...],
-) -> PydanticAITool[ObjectT]:
- if isinstance(tool_entry, Tool):
- return tool_entry
- return Tool(tool_entry)
-
-
-__all__ = [
- "PydanticAIBridgeLayer",
- "PydanticAIBridgeLayerDeps",
-]
diff --git a/dify-agent/src/agenton_collections/layers/pydantic_ai/history.py b/dify-agent/src/agenton_collections/layers/pydantic_ai/history.py
deleted file mode 100644
index ac91e4006a2..00000000000
--- a/dify-agent/src/agenton_collections/layers/pydantic_ai/history.py
+++ /dev/null
@@ -1,66 +0,0 @@
-"""Serializable pydantic-ai conversation history layer.
-
-This layer keeps pydantic-ai ``ModelMessage`` history inside Agenton's
-serializable ``runtime_state`` so compositor session snapshots can persist and
-restore typed messages without any separate storage protocol. The layer is
-intentionally state-only: it contributes no system prompts, user prompts, or
-tools, and it owns no live resources. Integrations should read
-``message_history`` before ``Agent.run(message_history=...)`` and then write
-back only the history shape they intend to persist after success, for example
-replacing with ``result.all_messages()`` or appending only
-``result.new_messages()`` when temporary prompt prefixes must stay ephemeral.
-"""
-
-from collections.abc import Sequence
-from typing import ClassVar, Final
-
-from pydantic import BaseModel, ConfigDict, Field
-from pydantic_ai.messages import ModelMessage
-
-from agenton.layers import EmptyLayerConfig, NoLayerDeps, PydanticAILayer
-
-
-PYDANTIC_AI_HISTORY_LAYER_TYPE_ID: Final[str] = "pydantic_ai.history"
-
-
-class PydanticAIHistoryRuntimeState(BaseModel):
- """Serializable history state stored in Agenton session snapshots."""
-
- messages: list[ModelMessage] = Field(default_factory=list)
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-class PydanticAIHistoryLayer(PydanticAILayer[NoLayerDeps, object, EmptyLayerConfig, PydanticAIHistoryRuntimeState]):
- """State-only layer that stores pydantic-ai message history.
-
- The mutable history lives only in ``runtime_state.messages``. Helper methods
- always assign fresh lists instead of mutating the stored list in place so
- Pydantic assignment validation continues to guard the serialized state.
- """
-
- type_id: ClassVar[str | None] = PYDANTIC_AI_HISTORY_LAYER_TYPE_ID
-
- @property
- def message_history(self) -> list[ModelMessage]:
- """Return a shallow copy of the stored message history."""
- return list(self.runtime_state.messages)
-
- def replace_messages(self, messages: Sequence[ModelMessage]) -> None:
- """Replace the stored history with a validated copy of ``messages``."""
- self.runtime_state.messages = list(messages)
-
- def append_messages(self, messages: Sequence[ModelMessage]) -> None:
- """Append ``messages`` while keeping assignment validation on write."""
- self.runtime_state.messages = [*self.runtime_state.messages, *messages]
-
- def clear(self) -> None:
- """Remove all stored history messages."""
- self.runtime_state.messages = []
-
-
-__all__ = [
- "PYDANTIC_AI_HISTORY_LAYER_TYPE_ID",
- "PydanticAIHistoryLayer",
- "PydanticAIHistoryRuntimeState",
-]
diff --git a/dify-agent/src/agenton_collections/transformers/__init__.py b/dify-agent/src/agenton_collections/transformers/__init__.py
deleted file mode 100644
index 9767d57fc3a..00000000000
--- a/dify-agent/src/agenton_collections/transformers/__init__.py
+++ /dev/null
@@ -1,8 +0,0 @@
-"""Transformer package marker for collection integrations.
-
-Import pydantic-ai transformer presets from
-``agenton_collections.transformers.pydantic_ai`` explicitly so default imports do
-not pull runtime bridge implementations into client-safe environments.
-"""
-
-__all__: list[str] = []
diff --git a/dify-agent/src/agenton_collections/transformers/pydantic_ai.py b/dify-agent/src/agenton_collections/transformers/pydantic_ai.py
deleted file mode 100644
index 81b5393a8c7..00000000000
--- a/dify-agent/src/agenton_collections/transformers/pydantic_ai.py
+++ /dev/null
@@ -1,85 +0,0 @@
-"""Pydantic AI compositor transformer presets.
-
-This module owns the pydantic-ai runtime dependency for transforming tagged
-agenton system prompt, user prompt, and tool items into pydantic-ai-compatible
-items.
-"""
-
-from collections.abc import Sequence
-from typing import Final
-
-from pydantic_ai import Tool
-
-from agenton.compositor import CompositorTransformerKwargs
-from agenton.layers.types import (
- AllPromptTypes,
- AllToolTypes,
- AllUserPromptTypes,
- PydanticAIPrompt,
- PydanticAITool,
- PydanticAIUserPrompt,
-)
-
-type PydanticAICompositorTransformerKwargs = CompositorTransformerKwargs[
- PydanticAIPrompt[object],
- PydanticAITool[object],
- AllPromptTypes,
- AllToolTypes,
- PydanticAIUserPrompt,
- AllUserPromptTypes,
-]
-
-
-def _pydantic_ai_prompt_transformer(
- prompts: Sequence[AllPromptTypes],
-) -> list[PydanticAIPrompt[object]]:
- result: list[PydanticAIPrompt[object]] = []
- for prompt in prompts:
- if prompt.kind == "plain":
- result.append((lambda value: lambda: value)(prompt.value))
- elif prompt.kind == "pydantic_ai":
- result.append(prompt.value)
- else:
- raise NotImplementedError(f"Unsupported prompt type: {type(prompt).__qualname__}.")
- return result
-
-
-def _pydantic_ai_user_prompt_transformer(
- prompts: Sequence[AllUserPromptTypes],
-) -> list[PydanticAIUserPrompt]:
- result: list[PydanticAIUserPrompt] = []
- for prompt in prompts:
- if prompt.kind == "plain":
- result.append(prompt.value)
- elif prompt.kind == "pydantic_ai":
- result.append(prompt.value)
- else:
- raise NotImplementedError(f"Unsupported user prompt type: {type(prompt).__qualname__}.")
- return result
-
-
-def _pydantic_ai_tool_transformer(
- tools: Sequence[AllToolTypes],
-) -> list[PydanticAITool[object]]:
- result: list[PydanticAITool[object]] = []
- for tool in tools:
- if tool.kind == "plain":
- result.append(Tool(tool.value))
- elif tool.kind == "pydantic_ai":
- result.append(tool.value)
- else:
- raise NotImplementedError(f"Unsupported tool type: {type(tool).__qualname__}.")
- return result
-
-
-PYDANTIC_AI_TRANSFORMERS: Final[PydanticAICompositorTransformerKwargs] = {
- "prompt_transformer": _pydantic_ai_prompt_transformer,
- "user_prompt_transformer": _pydantic_ai_user_prompt_transformer,
- "tool_transformer": _pydantic_ai_tool_transformer,
-}
-
-
-__all__ = [
- "PYDANTIC_AI_TRANSFORMERS",
- "PydanticAICompositorTransformerKwargs",
-]
diff --git a/dify-agent/src/dify_agent/adapters/shell/shellctl.py b/dify-agent/src/dify_agent/adapters/shell/shellctl.py
index 5af4e20afea..0b617549035 100644
--- a/dify-agent/src/dify_agent/adapters/shell/shellctl.py
+++ b/dify-agent/src/dify_agent/adapters/shell/shellctl.py
@@ -10,7 +10,7 @@ from __future__ import annotations
import posixpath
from collections.abc import Awaitable, Callable
from dataclasses import dataclass
-from typing import Protocol, TypeVar, cast
+from typing import Protocol, TypeVar, cast, override
import httpx2 as httpx
from shellctl.client import ShellctlClientError
@@ -109,6 +109,7 @@ class ShellctlCommands(ShellCommandProtocol):
home_dir: str | None = None
workspace_dir: str | None = None
+ @override
async def run(
self,
script: str,
@@ -136,6 +137,7 @@ class ShellctlCommands(ShellCommandProtocol):
)
)
+ @override
async def wait(
self,
job_id: str,
@@ -145,6 +147,7 @@ class ShellctlCommands(ShellCommandProtocol):
) -> ShellCommandResult:
return _from_job_result(await _run_client_call(self.client.wait(job_id, offset=offset, timeout=timeout)))
+ @override
async def read_output(
self,
job_id: str,
@@ -155,6 +158,7 @@ class ShellctlCommands(ShellCommandProtocol):
await _run_client_call(self.client.wait(job_id, offset=offset, timeout=_READ_OUTPUT_TIMEOUT_SECONDS))
)
+ @override
async def input(
self,
job_id: str,
@@ -165,6 +169,7 @@ class ShellctlCommands(ShellCommandProtocol):
) -> ShellCommandResult:
return _from_job_result(await _run_client_call(self.client.input(job_id, text, offset=offset, timeout=timeout)))
+ @override
async def interrupt(
self,
job_id: str,
@@ -173,9 +178,11 @@ class ShellctlCommands(ShellCommandProtocol):
) -> ShellCommandStatus:
return _from_job_status(await _run_client_call(self.client.terminate(job_id, grace_seconds=grace_seconds)))
+ @override
async def tail(self, job_id: str) -> ShellCommandResult:
return _from_job_result(await _run_client_call(self.client.tail(job_id)))
+ @override
async def delete(
self,
job_id: str,
diff --git a/dify-agent/src/dify_agent/layers/__init__.py b/dify-agent/src/dify_agent/layers/__init__.py
index 518fbf9bd93..c42cd002d25 100644
--- a/dify-agent/src/dify_agent/layers/__init__.py
+++ b/dify-agent/src/dify_agent/layers/__init__.py
@@ -1,3 +1,3 @@
-"""Dify-owned Agenton layer packages."""
+"""Dify modules and client-safe configuration DTOs."""
__all__: list[str] = []
diff --git a/dify-agent/src/dify_agent/layers/ask_human/__init__.py b/dify-agent/src/dify_agent/layers/ask_human/__init__.py
deleted file mode 100644
index 0138d7daf62..00000000000
--- a/dify-agent/src/dify_agent/layers/ask_human/__init__.py
+++ /dev/null
@@ -1,48 +0,0 @@
-"""Client-safe exports for Dify ask-human layer DTOs and schema types.
-
-The runtime layer implementation lives in ``layer.py`` and imports server-side
- execution helpers. Keep this package root import-safe for client code that only
- needs to build run requests or understand deferred payload shapes.
-"""
-
-from dify_agent.layers.ask_human.configs import (
- DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION,
- DIFY_ASK_HUMAN_LAYER_TYPE_ID,
- DifyAskHumanLayerConfig,
-)
-from dify_agent.layers.ask_human.schema import (
- AskHumanAction,
- AskHumanActionStyle,
- AskHumanField,
- AskHumanFieldType,
- AskHumanFileField,
- AskHumanFileListField,
- AskHumanParagraphField,
- AskHumanResultStatus,
- AskHumanSelectField,
- AskHumanSelectOption,
- AskHumanSelectedAction,
- AskHumanToolArgs,
- AskHumanToolResult,
- AskHumanUrgency,
-)
-
-__all__ = [
- "AskHumanAction",
- "AskHumanActionStyle",
- "AskHumanField",
- "AskHumanFieldType",
- "AskHumanFileField",
- "AskHumanFileListField",
- "AskHumanParagraphField",
- "AskHumanResultStatus",
- "AskHumanSelectField",
- "AskHumanSelectOption",
- "AskHumanSelectedAction",
- "AskHumanToolArgs",
- "AskHumanToolResult",
- "AskHumanUrgency",
- "DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION",
- "DIFY_ASK_HUMAN_LAYER_TYPE_ID",
- "DifyAskHumanLayerConfig",
-]
diff --git a/dify-agent/src/dify_agent/layers/ask_human/configs.py b/dify-agent/src/dify_agent/layers/ask_human/configs.py
deleted file mode 100644
index 87fd1a4af0b..00000000000
--- a/dify-agent/src/dify_agent/layers/ask_human/configs.py
+++ /dev/null
@@ -1,140 +0,0 @@
-"""Client-safe DTOs for the Dify ask-human layer.
-
-The public config controls only stable model-facing tool identity and guardrails.
-Delivery, recipient selection, timeout policy, and other operational behavior are
-intentionally out of scope for this layer and must stay outside the model-facing
-tool contract. Setting ``enabled=False`` disables both ask-human tool exposure
-and the prompt guidance that tells the model about these limits. Caller-provided
-limits are additionally capped by small server hard limits so one composition
-cannot widen the public deferred-tool surface arbitrarily. File field variants
-are part of the schema vocabulary for forward compatibility, but they remain
-invalid unless ``allow_file_fields=True`` and the allowed field-type list also
-permits them.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import ClassVar, Final
-
-from pydantic import ConfigDict, Field, field_validator, model_validator
-
-from agenton.layers import LayerConfig
-from dify_agent.layers.ask_human.schema import AskHumanFieldType
-
-
-DIFY_ASK_HUMAN_LAYER_TYPE_ID: Final[str] = "dify.ask_human"
-DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION: Final[str] = (
- "Ask a human for missing information or a decision that is required to continue. "
- "Use this only when the answer cannot be inferred from the conversation, available tools, or current context. "
- "Provide concise instructions, structured fields, and clear actions for the human."
-)
-
-_TOOL_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
-_HARD_MAX_FIELDS = 16
-_HARD_MAX_ACTIONS = 8
-_HARD_MAX_MARKDOWN_CHARS = 20_000
-_HARD_MAX_QUESTION_CHARS = 4_000
-_HARD_MAX_FIELD_LABEL_CHARS = 200
-_HARD_MAX_ACTION_LABEL_CHARS = 120
-_FILE_FIELD_TYPES: Final[frozenset[AskHumanFieldType]] = frozenset({"file", "file-list"})
-
-
-def _default_allowed_field_types() -> list[AskHumanFieldType]:
- return ["paragraph", "select"]
-
-
-class DifyAskHumanLayerConfig(LayerConfig):
- """Public config for the optional ask-human deferred tool layer.
-
- This DTO describes the exact model-facing guardrail surface that the runtime
- will both validate and surface back to the model through prompt guidance.
- ``enabled=False`` means callers keep the layer in composition data without
- exposing either the tool or its instructions for that run. Numeric limits are
- caller-configurable only within the server's hard caps, and file field types
- are rejected unless callers opt in with ``allow_file_fields=True``.
- """
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- enabled: bool = True
- tool_name: str = "ask_human"
- tool_description: str | None = None
- max_fields: int = Field(default=8, ge=0)
- max_actions: int = Field(default=4, ge=1)
- allowed_field_types: list[AskHumanFieldType] = Field(default_factory=_default_allowed_field_types)
- allow_file_fields: bool = False
- max_markdown_chars: int = Field(default=8_000, ge=0)
- max_question_chars: int = Field(default=1_000, ge=1)
- max_field_label_chars: int = Field(default=120, ge=1)
- max_action_label_chars: int = Field(default=80, ge=1)
-
- @property
- def effective_tool_description(self) -> str:
- """Return the configured description or the proposal default text."""
- return self.tool_description or DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION
-
- @field_validator("tool_name")
- @classmethod
- def _validate_tool_name(cls, value: str) -> str:
- if not _TOOL_NAME_PATTERN.fullmatch(value):
- raise ValueError("tool_name must be a valid tool identifier")
- return value
-
- @field_validator("tool_description")
- @classmethod
- def _normalize_tool_description(cls, value: str | None) -> str | None:
- if value is None:
- return None
- stripped = value.strip()
- return stripped or None
-
- @field_validator("allowed_field_types")
- @classmethod
- def _validate_allowed_field_types(cls, value: list[AskHumanFieldType]) -> list[AskHumanFieldType]:
- if len(set(value)) != len(value):
- raise ValueError("allowed_field_types must not contain duplicates")
- return value
-
- @field_validator(
- "max_fields",
- "max_actions",
- "max_markdown_chars",
- "max_question_chars",
- "max_field_label_chars",
- "max_action_label_chars",
- mode="after",
- )
- @classmethod
- def _validate_hard_limits(cls, value: int, info: object) -> int:
- field_name = getattr(info, "field_name", "value")
- hard_limits = {
- "max_fields": _HARD_MAX_FIELDS,
- "max_actions": _HARD_MAX_ACTIONS,
- "max_markdown_chars": _HARD_MAX_MARKDOWN_CHARS,
- "max_question_chars": _HARD_MAX_QUESTION_CHARS,
- "max_field_label_chars": _HARD_MAX_FIELD_LABEL_CHARS,
- "max_action_label_chars": _HARD_MAX_ACTION_LABEL_CHARS,
- }
- hard_limit = hard_limits[field_name]
- if value > hard_limit:
- raise ValueError(f"{field_name} must be <= {hard_limit}")
- return value
-
- @model_validator(mode="after")
- def _validate_file_field_policy(self) -> DifyAskHumanLayerConfig:
- if not self.allow_file_fields:
- forbidden = [field_type for field_type in self.allowed_field_types if field_type in _FILE_FIELD_TYPES]
- if forbidden:
- joined = ", ".join(forbidden)
- raise ValueError(
- f"allowed_field_types cannot include file field types when allow_file_fields is false: {joined}"
- )
- return self
-
-
-__all__ = [
- "DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION",
- "DIFY_ASK_HUMAN_LAYER_TYPE_ID",
- "DifyAskHumanLayerConfig",
-]
diff --git a/dify-agent/src/dify_agent/layers/ask_human/layer.py b/dify-agent/src/dify_agent/layers/ask_human/layer.py
deleted file mode 100644
index 399f28ab063..00000000000
--- a/dify-agent/src/dify_agent/layers/ask_human/layer.py
+++ /dev/null
@@ -1,275 +0,0 @@
-"""Runtime ask-human layer built on pydantic-ai external deferred tools.
-
-The layer contributes one optional external tool plus one prompt hint. The tool
-never executes Python during the initial run; instead the model emits an
-external deferred tool call that Dify Agent returns through ``run_succeeded`` as
-``deferred_tool_call``. Guardrails are enforced in two places:
-
-* prompt/tool-definition guidance nudges the model toward valid requests, and
-* runtime validation normalizes default actions and rejects out-of-policy calls.
-
-The layer stays product-neutral: downstream systems decide delivery, recipients,
-timeouts, and authorization for the human request.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any, ClassVar, cast
-
-from pydantic import JsonValue, ValidationError
-from pydantic_ai import Tool
-from pydantic_ai.exceptions import ModelRetry
-from pydantic_ai.tools import ArgsValidatorFunc, DeferredToolRequests, RunContext, ToolDefinition
-from typing_extensions import Self, override
-
-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PydanticAILayer, PydanticAIPrompt, PydanticAITool
-from dify_agent.layers.ask_human.configs import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
-from dify_agent.layers.ask_human.schema import (
- AskHumanAction,
- AskHumanField,
- AskHumanToolArgs,
-)
-from dify_agent.protocol.schemas import DeferredToolCallPayload, RunComposition
-
-
-_ASK_HUMAN_DEFERRED_SCHEMA_VERSION = 1
-_DEFAULT_SUBMIT_ACTION = AskHumanAction(id="submit", label="Submit", style="primary")
-
-
-@dataclass(slots=True)
-class DifyAskHumanLayer(PydanticAILayer[NoLayerDeps, object, DifyAskHumanLayerConfig, EmptyRuntimeState]):
- """State-free pydantic-ai layer that exposes the ask-human deferred tool."""
-
- type_id: ClassVar[str | None] = DIFY_ASK_HUMAN_LAYER_TYPE_ID
-
- config: DifyAskHumanLayerConfig
-
- @classmethod
- @override
- def from_config(cls, config: DifyAskHumanLayerConfig) -> Self:
- """Create the layer from validated public config."""
- return cls(config=DifyAskHumanLayerConfig.model_validate(config))
-
- @property
- @override
- def prefix_prompts(self) -> list[PydanticAIPrompt[object]]:
- if not self.config.enabled:
- return []
- return [self.build_prompt_hint]
-
- @property
- @override
- def tools(self) -> list[PydanticAITool[object]]:
- if not self.config.enabled:
- return []
- return [
- Tool(
- self._never_executed_tool,
- takes_ctx=True,
- name=self.config.tool_name,
- description=self.config.effective_tool_description,
- prepare=self._prepare_tool_definition,
- args_validator=cast(ArgsValidatorFunc[object, ...], self._validate_tool_args),
- sequential=True,
- )
- ]
-
- def build_prompt_hint(self) -> str:
- """Return the model-facing instruction text for ask-human guardrails."""
- allowed_field_types = ", ".join(self.config.allowed_field_types) if self.config.allowed_field_types else "none"
- file_field_status = "enabled" if self.config.allow_file_fields else "disabled"
- if self.config.max_fields == 0:
- field_count_hint = "Do not add any fields."
- else:
- field_count_hint = f"Use at most {self.config.max_fields} field(s)."
- return (
- f"You may call the external tool '{self.config.tool_name}' only when human input is required to continue. "
- "Do not ask a human for information that can be inferred from the conversation, current context, or other tools.\n\n"
- f"Ask-human guardrails:\n"
- f"- Allowed field types: {allowed_field_types}.\n"
- f"- File upload fields are {file_field_status}.\n"
- f"- {field_count_hint}\n"
- f"- Use at most {self.config.max_actions} action(s).\n"
- f"- Keep 'question' under {self.config.max_question_chars} characters.\n"
- f"- Keep 'markdown' under {self.config.max_markdown_chars} characters.\n"
- f"- Keep each field label under {self.config.max_field_label_chars} characters.\n"
- f"- Keep each action label under {self.config.max_action_label_chars} characters.\n"
- "- If you omit actions, the system will add one primary action: Submit.\n"
- "Prefer concise, structured requests that stay comfortably within these limits."
- )
-
- def build_deferred_tool_call_payload(self, requests: DeferredToolRequests) -> DeferredToolCallPayload:
- """Validate and normalize the single supported deferred ask-human call."""
- if requests.approvals:
- raise ValueError("ask_human does not support approval requests; use external deferred calls only")
-
- call_count = len(requests.calls)
- if call_count != 1:
- raise ValueError(f"ask_human supports exactly one deferred call per run in this version; got {call_count}.")
-
- call = requests.calls[0]
- if call.tool_name != self.config.tool_name:
- raise ValueError(f"ask_human deferred tool name must be '{self.config.tool_name}', got '{call.tool_name}'.")
-
- args = self._validate_and_normalize_tool_args(
- title=None,
- question="",
- markdown=None,
- fields=[],
- actions=[],
- urgency="normal",
- raw_args=call.args,
- )
- return DeferredToolCallPayload(
- tool_call_id=call.tool_call_id,
- tool_name=call.tool_name,
- args=cast(JsonValue, args.model_dump(mode="json")),
- metadata={
- "layer_type": self.type_id,
- "tool_name": self.config.tool_name,
- "schema_version": _ASK_HUMAN_DEFERRED_SCHEMA_VERSION,
- },
- )
-
- def _prepare_tool_definition(self, _ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:
- """Convert the ask-human tool into a pydantic-ai external deferred tool."""
- del tool_def
- return ToolDefinition(
- name=self.config.tool_name,
- description=self.config.effective_tool_description,
- parameters_json_schema=cast(dict[str, Any], AskHumanToolArgs.model_json_schema()),
- strict=False,
- sequential=True,
- kind="external",
- )
-
- async def _never_executed_tool(
- self,
- _ctx: RunContext[object],
- *,
- title: str | None = None,
- question: str,
- markdown: str | None = None,
- fields: list[AskHumanField] | None = None,
- actions: list[AskHumanAction] | None = None,
- urgency: str = "normal",
- ) -> str:
- del title, question, markdown, fields, actions, urgency
- raise RuntimeError("ask_human is an external deferred tool and should not execute during the initial run")
-
- def _validate_tool_args(
- self,
- _ctx: RunContext[object],
- *,
- title: str | None = None,
- question: str,
- markdown: str | None = None,
- fields: list[AskHumanField] | None = None,
- actions: list[AskHumanAction] | None = None,
- urgency: str = "normal",
- ) -> None:
- try:
- _ = self._validate_and_normalize_tool_args(
- title=title,
- question=question,
- markdown=markdown,
- fields=fields or [],
- actions=actions or [],
- urgency=urgency,
- )
- except (ValidationError, ValueError) as exc:
- raise ModelRetry(str(exc)) from exc
-
- def _validate_and_normalize_tool_args(
- self,
- *,
- title: str | None,
- question: str,
- markdown: str | None,
- fields: list[AskHumanField],
- actions: list[AskHumanAction],
- urgency: str,
- raw_args: str | dict[str, Any] | None = None,
- ) -> AskHumanToolArgs:
- if raw_args is not None:
- args = _validate_tool_args_payload(raw_args)
- else:
- args = AskHumanToolArgs(
- title=title,
- question=question,
- markdown=markdown,
- fields=fields,
- actions=actions,
- urgency=cast(Any, urgency),
- )
-
- if len(args.fields) > self.config.max_fields:
- raise ValueError(f"ask_human fields must contain at most {self.config.max_fields} item(s)")
-
- normalized_actions = list(args.actions)
- if not normalized_actions:
- normalized_actions = [_DEFAULT_SUBMIT_ACTION.model_copy()]
- if len(normalized_actions) > self.config.max_actions:
- raise ValueError(f"ask_human actions must contain at most {self.config.max_actions} item(s)")
-
- if len(args.question) > self.config.max_question_chars:
- raise ValueError(f"ask_human question must be <= {self.config.max_question_chars} characters")
- if args.markdown is not None and len(args.markdown) > self.config.max_markdown_chars:
- raise ValueError(f"ask_human markdown must be <= {self.config.max_markdown_chars} characters")
-
- allowed_field_types = set(self.config.allowed_field_types)
- for field in args.fields:
- if field.type not in allowed_field_types:
- raise ValueError(f"ask_human field type '{field.type}' is not allowed by this layer config")
- if len(field.label) > self.config.max_field_label_chars:
- raise ValueError(
- f"ask_human field label '{field.label}' must be <= {self.config.max_field_label_chars} characters"
- )
- if not self.config.allow_file_fields and field.type in {"file", "file-list"}:
- raise ValueError("ask_human file fields are disabled by this layer config")
-
- for action in normalized_actions:
- if len(action.label) > self.config.max_action_label_chars:
- raise ValueError(
- f"ask_human action label '{action.label}' must be <= {self.config.max_action_label_chars} characters"
- )
-
- return args.model_copy(update={"actions": normalized_actions})
-
-
-def validate_ask_human_layer_composition(composition: RunComposition) -> None:
- """Reject unsupported public ask-human layer graph shapes."""
- ask_human_layers = [layer.name for layer in composition.layers if layer.type == DIFY_ASK_HUMAN_LAYER_TYPE_ID]
- if len(ask_human_layers) > 1:
- names = ", ".join(ask_human_layers)
- raise ValueError(f"Only one '{DIFY_ASK_HUMAN_LAYER_TYPE_ID}' layer is supported. Found layers: {names}.")
-
-
-def get_ask_human_layer(run: Any) -> DifyAskHumanLayer | None:
- """Return the active ask-human layer when one is present and enabled."""
- matched: list[DifyAskHumanLayer] = []
- for slot in run.slots.values():
- layer = slot.layer
- if isinstance(layer, DifyAskHumanLayer):
- matched.append(layer)
- if not matched:
- return None
- if len(matched) > 1:
- raise ValueError(f"Only one '{DIFY_ASK_HUMAN_LAYER_TYPE_ID}' layer is supported per run.")
-
- layer = matched[0]
- return layer if layer.config.enabled else None
-
-
-def _validate_tool_args_payload(raw_args: str | dict[str, Any]) -> AskHumanToolArgs:
- if isinstance(raw_args, str):
- return AskHumanToolArgs.model_validate_json(raw_args or "{}")
- return AskHumanToolArgs.model_validate(raw_args or {})
-
-
-__all__ = [
- "DifyAskHumanLayer",
- "get_ask_human_layer",
- "validate_ask_human_layer_composition",
-]
diff --git a/dify-agent/src/dify_agent/layers/ask_human/schema.py b/dify-agent/src/dify_agent/layers/ask_human/schema.py
deleted file mode 100644
index 59fb9d3fc70..00000000000
--- a/dify-agent/src/dify_agent/layers/ask_human/schema.py
+++ /dev/null
@@ -1,234 +0,0 @@
-"""Product-neutral schemas for the Dify ask-human deferred tool contract.
-
-These models describe the model-facing tool arguments and the later human result
-payload expected by resumed runs. Config-specific guardrails such as maximum
-counts, allowed field types, or per-install length limits are enforced by
-``dify_agent.layers.ask_human.layer`` so this module stays import-safe for
-client code that only needs the stable wire/schema shapes.
-"""
-
-from __future__ import annotations
-
-import re
-from typing import Annotated, ClassVar, Literal
-
-from pydantic import BaseModel, ConfigDict, Field, JsonValue, ValidationInfo, field_validator, model_validator
-
-
-_IDENTIFIER_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
-
-type AskHumanFieldType = Literal["paragraph", "select", "file", "file-list"]
-type AskHumanActionStyle = Literal["default", "primary", "destructive"]
-type AskHumanUrgency = Literal["normal", "high"]
-type AskHumanResultStatus = Literal["submitted", "timeout", "cancelled", "unavailable"]
-
-
-def is_valid_identifier(value: str) -> bool:
- """Return whether ``value`` matches the stable ask-human identifier rules."""
- return bool(_IDENTIFIER_PATTERN.fullmatch(value))
-
-
-def _require_non_blank(value: str, *, label: str) -> str:
- if not value.strip():
- raise ValueError(f"{label} must not be blank")
- return value
-
-
-class AskHumanSelectOption(BaseModel):
- """One selectable option for an ask-human select field."""
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- value: str = Field(min_length=1)
- label: str = Field(min_length=1)
-
- @field_validator("value", "label")
- @classmethod
- def _validate_non_blank(cls, value: str, info: ValidationInfo) -> str:
- return _require_non_blank(value, label=f"select option {info.field_name}")
-
-
-class AskHumanFieldBase(BaseModel):
- """Shared field properties for ask-human form fields."""
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- name: str = Field(min_length=1)
- label: str = Field(min_length=1)
- required: bool = False
-
- @field_validator("name")
- @classmethod
- def _validate_name(cls, value: str) -> str:
- if not is_valid_identifier(value):
- raise ValueError("field name must be a valid identifier")
- return value
-
- @field_validator("label")
- @classmethod
- def _validate_label(cls, value: str) -> str:
- return _require_non_blank(value, label="field label")
-
-
-class AskHumanParagraphField(AskHumanFieldBase):
- """Free-text paragraph field."""
-
- type: Literal["paragraph"] = "paragraph"
- placeholder: str | None = None
- default: str | None = None
-
-
-class AskHumanSelectField(AskHumanFieldBase):
- """Single-choice select field."""
-
- type: Literal["select"] = "select"
- options: list[AskHumanSelectOption] = Field(default_factory=list)
- default: str | None = None
-
- @model_validator(mode="after")
- def _validate_options(self) -> AskHumanSelectField:
- if not self.options:
- raise ValueError("select fields must define at least one option")
-
- seen_values: set[str] = set()
- for option in self.options:
- if option.value in seen_values:
- raise ValueError(f"select field '{self.name}' contains duplicate option value '{option.value}'")
- seen_values.add(option.value)
-
- if self.default is not None and self.default not in seen_values:
- raise ValueError(f"select field '{self.name}' default must match one of its option values")
- return self
-
-
-class AskHumanFileField(AskHumanFieldBase):
- """Single-file upload field."""
-
- type: Literal["file"] = "file"
-
-
-class AskHumanFileListField(AskHumanFieldBase):
- """Multi-file upload field."""
-
- type: Literal["file-list"] = "file-list"
- max_files: int | None = Field(default=None, ge=1)
-
-
-type AskHumanField = Annotated[
- AskHumanParagraphField | AskHumanSelectField | AskHumanFileField | AskHumanFileListField,
- Field(discriminator="type"),
-]
-
-
-class AskHumanAction(BaseModel):
- """One human-visible action rendered with an ask-human request."""
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- id: str = Field(min_length=1)
- label: str = Field(min_length=1)
- style: AskHumanActionStyle = "default"
-
- @field_validator("id")
- @classmethod
- def _validate_id(cls, value: str) -> str:
- if not is_valid_identifier(value):
- raise ValueError("action id must be a valid identifier")
- return value
-
- @field_validator("label")
- @classmethod
- def _validate_label(cls, value: str) -> str:
- return _require_non_blank(value, label="action label")
-
-
-class AskHumanSelectedAction(BaseModel):
- """Action metadata returned with a human-submitted result."""
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- id: str = Field(min_length=1)
- label: str = Field(min_length=1)
-
- @field_validator("id")
- @classmethod
- def _validate_id(cls, value: str) -> str:
- if not is_valid_identifier(value):
- raise ValueError("selected action id must be a valid identifier")
- return value
-
- @field_validator("label")
- @classmethod
- def _validate_label(cls, value: str) -> str:
- return _require_non_blank(value, label="selected action label")
-
-
-class AskHumanToolArgs(BaseModel):
- """Arguments accepted by the ask-human external deferred tool."""
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- title: str | None = None
- question: str = Field(min_length=1)
- markdown: str | None = None
- fields: list[AskHumanField] = Field(default_factory=list)
- actions: list[AskHumanAction] = Field(default_factory=list)
- urgency: AskHumanUrgency = "normal"
-
- @field_validator("question")
- @classmethod
- def _validate_question(cls, value: str) -> str:
- return _require_non_blank(value, label="question")
-
- @field_validator("title")
- @classmethod
- def _validate_title(cls, value: str | None) -> str | None:
- if value is None:
- return None
- return _require_non_blank(value, label="title")
-
- @model_validator(mode="after")
- def _validate_unique_ids(self) -> AskHumanToolArgs:
- field_names: set[str] = set()
- for field in self.fields:
- if field.name in field_names:
- raise ValueError(f"field name '{field.name}' must be unique")
- field_names.add(field.name)
-
- action_ids: set[str] = set()
- for action in self.actions:
- if action.id in action_ids:
- raise ValueError(f"action id '{action.id}' must be unique")
- action_ids.add(action.id)
- return self
-
-
-class AskHumanToolResult(BaseModel):
- """Expected value shape for a later deferred ask-human tool result."""
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- status: AskHumanResultStatus
- action: AskHumanSelectedAction | None = None
- values: dict[str, JsonValue] = Field(default_factory=dict)
- message: str | None = None
- rendered_content: str | None = None
-
-
-__all__ = [
- "AskHumanAction",
- "AskHumanActionStyle",
- "AskHumanField",
- "AskHumanFieldType",
- "AskHumanFileField",
- "AskHumanFileListField",
- "AskHumanParagraphField",
- "AskHumanResultStatus",
- "AskHumanSelectField",
- "AskHumanSelectOption",
- "AskHumanSelectedAction",
- "AskHumanToolArgs",
- "AskHumanToolResult",
- "AskHumanUrgency",
- "is_valid_identifier",
-]
diff --git a/dify-agent/src/dify_agent/layers/config/__init__.py b/dify-agent/src/dify_agent/layers/config/__init__.py
index f5c3d0c4b3a..c5fea5d92a5 100644
--- a/dify-agent/src/dify_agent/layers/config/__init__.py
+++ b/dify-agent/src/dify_agent/layers/config/__init__.py
@@ -1,7 +1,6 @@
"""Client-safe exports for the Dify config runtime catalog DTOs."""
from dify_agent.layers.config.configs import (
- DIFY_CONFIG_LAYER_TYPE_ID,
DifyConfigFileConfig,
DifyConfigLayerConfig,
DifyConfigRuntimeState,
@@ -10,7 +9,6 @@ from dify_agent.layers.config.configs import (
)
__all__ = [
- "DIFY_CONFIG_LAYER_TYPE_ID",
"DifyConfigFileConfig",
"DifyConfigLayerConfig",
"DifyConfigRuntimeState",
diff --git a/dify-agent/src/dify_agent/layers/config/configs.py b/dify-agent/src/dify_agent/layers/config/configs.py
index 5f8eae360eb..664b14083b4 100644
--- a/dify-agent/src/dify_agent/layers/config/configs.py
+++ b/dify-agent/src/dify_agent/layers/config/configs.py
@@ -1,14 +1,9 @@
"""Client-safe DTOs for the Dify config declaration layer."""
-from typing import ClassVar, Final, Literal
+from typing import ClassVar, Literal
from pydantic import BaseModel, ConfigDict, Field
-from agenton.layers import LayerConfig
-
-
-DIFY_CONFIG_LAYER_TYPE_ID: Final[str] = "dify.config"
-
class DifyConfigVersionConfig(BaseModel):
"""Agent config version metadata visible to the runtime prompt."""
@@ -41,9 +36,11 @@ class DifyConfigFileConfig(BaseModel):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-class DifyConfigLayerConfig(LayerConfig):
+class DifyConfigLayerConfig(BaseModel):
"""Agent Soul config context plus eager-pull instructions for prompt mentions."""
+ shell: str = "shell"
+
agent_id: str | None = None
config_version: DifyConfigVersionConfig | None = None
skills: list[DifyConfigSkillConfig] = Field(default_factory=list)
@@ -57,30 +54,15 @@ class DifyConfigLayerConfig(LayerConfig):
class DifyConfigRuntimeState(BaseModel):
- """Serializable config-layer values computed once during context entry.
-
- ``config_cli_help`` stores pre-rendered shell-visible ``dify-agent`` help snippets
- for config commands and file upload/download commands.
-
- The ``push_spec_*`` fields are compatibility leftovers from the removed root
- JSON-spec config mutation workflow. This change keeps them in the runtime-state
- schema to avoid snapshot churn, but new code should treat them as inert
- compatibility fields rather than active prompt data.
- """
+ """Persisted outputs of completed shell-backed config pulls."""
pulled_skill_outputs: dict[str, str] = Field(default_factory=dict)
pulled_file_outputs: dict[str, str] = Field(default_factory=dict)
- config_context_json: str = ""
- config_cli_help: dict[str, str] = Field(default_factory=dict)
- push_spec_semantics: str = ""
- push_spec_json_schema: str = ""
- push_spec_example: str = ""
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", validate_assignment=True)
__all__ = [
- "DIFY_CONFIG_LAYER_TYPE_ID",
"DifyConfigFileConfig",
"DifyConfigLayerConfig",
"DifyConfigRuntimeState",
diff --git a/dify-agent/src/dify_agent/layers/config/layer.py b/dify-agent/src/dify_agent/layers/config/layer.py
index 730cdc6b15c..08060a4dea0 100644
--- a/dify-agent/src/dify_agent/layers/config/layer.py
+++ b/dify-agent/src/dify_agent/layers/config/layer.py
@@ -1,23 +1,29 @@
-"""Runtime Dify config layer with shell-backed eager pulls."""
+"""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 ClassVar
+from typing import override
-from typing_extensions import Self, override
-from agenton.layers import LayerDeps, PlainLayer
+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 (
- DIFY_CONFIG_LAYER_TYPE_ID,
DifyConfigLayerConfig,
DifyConfigRuntimeState,
)
-from dify_agent.layers.shell.layer import DifyShellLayer
+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"
@@ -52,64 +58,65 @@ _AGENT_FILE_CLI_HELP_COMMANDS: dict[str, tuple[str, ...]] = {
"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}
+_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 DifyConfigDeps(LayerDeps):
- shell: DifyShellLayer # pyright: ignore[reportUninitializedInstanceVariable]
+class Config(DifyConfigLayerConfig):
+ pass
-@dataclass(slots=True)
-class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConfigRuntimeState]):
- """Config runtime layer that materializes prompt-mentioned targets via shell."""
+class State(DifyConfigRuntimeState):
+ initialized: bool = False
- type_id: ClassVar[str | None] = DIFY_CONFIG_LAYER_TYPE_ID
- config: DifyConfigLayerConfig
+class Capability(AbstractCapability[Deps]):
+ """First-run eager pulls with explicit JSON writeback and native ordering."""
- @classmethod
- @override
- def from_config(cls, config: DifyConfigLayerConfig) -> Self:
- return cls(config=DifyConfigLayerConfig.model_validate(config))
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
- @property
@override
- def prefix_prompts(self) -> list[str]:
- return [self.build_prompt_context()]
+ def get_ordering(self) -> CapabilityOrdering:
+ return CapabilityOrdering(wrapped_by=[ShellCapability], requires=[ShellCapability])
- @property
@override
- def suffix_prompts(self) -> list[str]:
- return [self.build_suffix_prompt()]
+ def get_instructions(self):
+ return self._instructions
- @override
- async def on_context_create(self) -> None:
- await self._initialize_context()
+ 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 on_context_resume(self) -> None:
- return None
+ 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()
- async def _initialize_context(self) -> None:
- self._initialize_runtime_prompt_state()
- await self._pull_mentioned_targets()
- def _initialize_runtime_prompt_state(self) -> None:
- command_paths = dict(_CONFIG_CLI_HELP_COMMANDS)
- if self._config_writable:
- command_paths.update(_CONFIG_CLI_MUTATION_HELP_COMMANDS)
- command_paths.update(_AGENT_FILE_CLI_HELP_COMMANDS)
- self.runtime_state.config_context_json = self._format_config_context_json()
- self.runtime_state.config_cli_help = {
- command: render_agent_stub_cli_help(args) for command, args in command_paths.items()
- }
- self.runtime_state.push_spec_semantics = ""
- self.runtime_state.push_spec_json_schema = ""
- self.runtime_state.push_spec_example = ""
+@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] = []
@@ -141,17 +148,11 @@ class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConf
return "\n\n".join(section for section in sections if section)
def build_suffix_prompt(self) -> str:
- sections: list[str] = []
- if self.runtime_state.config_context_json:
- sections.append(
- f"{_CONFIG_CONTEXT_HEADING}\n"
- f"{_format_command_output(_CONFIG_CONTEXT_COMMAND, self.runtime_state.config_context_json)}"
- )
- usage_lines = [_CONFIG_CLI_USAGE_PROMPT]
- if cli_help := self._format_config_cli_help():
- usage_lines.append(cli_help)
- if file_cli_help := self._format_agent_file_cli_help():
- usage_lines.append(file_cli_help)
+ 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)
@@ -160,26 +161,19 @@ class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConf
return self.config.config_version is not None and self.config.config_version.writable
def _format_config_cli_help(self) -> str:
- commands = list(_CONFIG_CLI_HELP_COMMANDS)
+ commands = dict(_CONFIG_CLI_HELP_COMMANDS)
if self._config_writable:
- commands.extend(_CONFIG_CLI_MUTATION_HELP_COMMANDS)
+ commands.update(_CONFIG_CLI_MUTATION_HELP_COMMANDS)
command_sections = [
- _format_command_output(command, self.runtime_state.config_cli_help[command])
- for command in commands
- if command in self.runtime_state.config_cli_help
+ _format_command_output(command, render_agent_stub_cli_help(args)) for command, args in commands.items()
]
- if not command_sections:
- return ""
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, self.runtime_state.config_cli_help[command])
- for command in _AGENT_FILE_CLI_HELP_COMMANDS
- if command in self.runtime_state.config_cli_help
+ _format_command_output(command, render_agent_stub_cli_help(args))
+ for command, args in _AGENT_FILE_CLI_HELP_COMMANDS.items()
]
- if not command_sections:
- return ""
return (
"Agent file CLI reference for installed `dify-agent`:\n"
+ "\n\n".join(command_sections)
@@ -210,7 +204,7 @@ class DifyConfigLayer(PlainLayer[DifyConfigDeps, DifyConfigLayerConfig, DifyConf
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.deps.shell.run_remote_script(
+ result = await self.shell.run_remote_script(
script,
inject_agent_stub_env=True,
)
@@ -296,4 +290,4 @@ def _format_command_output(command: str, output: str) -> str:
return f"Command:\n$ {command}\nOutput:\n{output}"
-__all__ = ["DifyConfigLayer", "DifyConfigLayerError"]
+__all__ = ["Config", "State", "Capability", "DifyConfigLayerError"]
diff --git a/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py b/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py
index dd8b09574cf..24eaeb9a1dd 100644
--- a/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py
+++ b/dify-agent/src/dify_agent/layers/dify_core_tools/__init__.py
@@ -1,14 +1,12 @@
"""Client-safe exports for the Dify core-tools layer DTOs and type ids."""
from dify_agent.layers.dify_core_tools.configs import (
- DIFY_CORE_TOOLS_LAYER_TYPE_ID,
DifyCoreToolConfig,
DifyCoreToolProviderType,
DifyCoreToolsLayerConfig,
)
__all__ = [
- "DIFY_CORE_TOOLS_LAYER_TYPE_ID",
"DifyCoreToolConfig",
"DifyCoreToolProviderType",
"DifyCoreToolsLayerConfig",
diff --git a/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py b/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py
index 19a25898cf8..dc6ddb5f694 100644
--- a/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py
+++ b/dify-agent/src/dify_agent/layers/dify_core_tools/configs.py
@@ -1,4 +1,4 @@
-"""Client-safe DTOs for the Dify core-tools Agenton layer.
+"""Client-safe DTOs for the Dify core-tools layer.
This layer exposes API-routed tool invocations for the Dify-owned provider
families that should execute inside the API service boundary: `plugin`,
@@ -9,23 +9,20 @@ not need to inspect provider internals or storage state.
from __future__ import annotations
-from typing import ClassVar, Final, Literal
+from typing import ClassVar, Literal
-from pydantic import ConfigDict, Field, JsonValue
+from pydantic import BaseModel, ConfigDict, Field, JsonValue
-from agenton.layers import LayerConfig
from dify_agent.layers.dify_plugin.configs import DifyPluginToolParameter
type DifyCoreToolProviderType = Literal["plugin", "builtin", "api", "workflow", "mcp"]
-DIFY_CORE_TOOLS_LAYER_TYPE_ID: Final[str] = "dify.core.tools"
-
def _default_parameters_json_schema() -> dict[str, JsonValue]:
return {"type": "object", "properties": {}, "required": []}
-class DifyCoreToolConfig(LayerConfig):
+class DifyCoreToolConfig(BaseModel):
"""Prepared API-routed tool declaration exposed to the model."""
provider_type: DifyCoreToolProviderType
@@ -41,9 +38,11 @@ class DifyCoreToolConfig(LayerConfig):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
-class DifyCoreToolsLayerConfig(LayerConfig):
+class DifyCoreToolsLayerConfig(BaseModel):
"""Public config for the Dify core-tools layer."""
+ execution_context: str = "execution_context"
+
tools: list[DifyCoreToolConfig] = Field(default_factory=list)
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
diff --git a/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py b/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py
index fcd4e7eede4..0b8c5725e48 100644
--- a/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py
+++ b/dify-agent/src/dify_agent/layers/dify_core_tools/layer.py
@@ -10,89 +10,69 @@ provider-local state stay in the API process.
from __future__ import annotations
from copy import deepcopy
-from dataclasses import dataclass
-from typing import ClassVar, cast
+from dataclasses import replace
+from typing import cast, override
-import httpx
from pydantic import JsonValue
from pydantic_ai import RunContext, Tool
from pydantic_ai.tools import ToolDefinition
-from typing_extensions import Self, override
-from agenton.layers import LayerDeps, PlainLayer
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai.toolsets import FunctionToolset
+from dify_agent.runtime.context import Deps
from dify_agent.layers.dify_core_tools.client import (
DifyCoreToolsClient,
DifyCoreToolsClientConfigurationError,
DifyCoreToolsClientError,
)
from dify_agent.layers.dify_core_tools.configs import (
- DIFY_CORE_TOOLS_LAYER_TYPE_ID,
DifyCoreToolConfig,
DifyCoreToolsLayerConfig,
)
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
+
CORE_TOOL_STRICT = False
TEMPORARY_UNAVAILABLE_OBSERVATION = "Tool is temporarily unavailable. Please continue without it if possible."
-class DifyCoreToolsDeps(LayerDeps):
- """Dependencies required by `DifyCoreToolsLayer`."""
+class Config(DifyCoreToolsLayerConfig):
+ pass
- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
-@dataclass(slots=True)
-class DifyCoreToolsLayer(PlainLayer[DifyCoreToolsDeps, DifyCoreToolsLayerConfig]):
- """Layer that resolves API-routed Dify tools into Pydantic AI tools."""
- type_id: ClassVar[str | None] = DIFY_CORE_TOOLS_LAYER_TYPE_ID
+class Toolset(FunctionToolset[Deps]):
+ """Expose API-prepared schemas and borrow the lifespan API client."""
- config: DifyCoreToolsLayerConfig
- inner_api_url: str
- inner_api_key: str
+ def __init__(self, name: str):
+ super().__init__(id=name)
+ self.name = name
+ self._loaded = False
- @classmethod
@override
- def from_config(cls, config: DifyCoreToolsLayerConfig) -> Self:
- del config
- raise TypeError("DifyCoreToolsLayer requires server-side Dify API settings and must use a provider factory.")
-
- @classmethod
- def from_config_with_settings(
- cls,
- config: DifyCoreToolsLayerConfig,
- *,
- inner_api_url: str,
- inner_api_key: str,
- ) -> Self:
- return cls(
- config=DifyCoreToolsLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- )
-
- async def get_tools(self, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:
- if http_client.is_closed:
- raise RuntimeError("DifyCoreToolsLayer.get_tools() requires an open shared HTTP client.")
-
- execution_context = self.deps.execution_context.config
- client = DifyCoreToolsClient(
- base_url=self.inner_api_url,
- api_key=self.inner_api_key,
- http_client=http_client,
- )
- tools: list[Tool[object]] = []
- for tool_config in self.config.tools:
- tools.append(
- self._build_tool(
- client=client,
- execution_context=execution_context,
- tool_config=tool_config,
- )
+ async def get_tools(self, ctx: RunContext[Deps]):
+ if not self._loaded:
+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])
+ execution_context = DifyExecutionContextLayerConfig.model_validate(
+ ctx.deps.layers[config.execution_context]["config"]
)
- return tools
+ http_client = ctx.deps.services.dify_api_http_client
+ if http_client.is_closed:
+ raise RuntimeError("Core tools require an open shared HTTP client.")
+ client = DifyCoreToolsClient(
+ base_url=ctx.deps.services.inner_api_url,
+ api_key=ctx.deps.services.inner_api_key,
+ http_client=http_client,
+ )
+ for tool_config in config.tools:
+ self.add_tool(
+ self._build_tool(client=client, execution_context=execution_context, tool_config=tool_config)
+ )
+ self._loaded = True
+ return await super().get_tools(ctx)
@staticmethod
def _build_tool(
@@ -100,12 +80,12 @@ class DifyCoreToolsLayer(PlainLayer[DifyCoreToolsDeps, DifyCoreToolsLayerConfig]
client: DifyCoreToolsClient,
execution_context: DifyExecutionContextLayerConfig,
tool_config: DifyCoreToolConfig,
- ) -> Tool[object]:
+ ) -> Tool[Deps]:
tool_name = tool_config.name or tool_config.tool_name
tool_description = tool_config.description or tool_name
tool_schema = deepcopy(tool_config.parameters_json_schema)
- async def invoke_tool(_ctx: RunContext[object], **tool_arguments: object) -> str:
+ async def invoke_tool(_ctx: RunContext[Deps], **tool_arguments: object) -> str:
try:
response = await client.invoke(
execution_context=execution_context,
@@ -118,20 +98,8 @@ class DifyCoreToolsLayer(PlainLayer[DifyCoreToolsDeps, DifyCoreToolsLayerConfig]
except DifyCoreToolsClientError as exc:
return _tool_error_text(tool_name=tool_name, error=exc)
- async def prepare_tool_definition(_ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:
- return ToolDefinition(
- name=tool_def.name,
- description=tool_def.description,
- parameters_json_schema=tool_schema,
- strict=CORE_TOOL_STRICT,
- sequential=tool_def.sequential,
- metadata=tool_def.metadata,
- timeout=tool_def.timeout,
- defer_loading=tool_def.defer_loading,
- kind=tool_def.kind,
- return_schema=tool_def.return_schema,
- include_return_schema=tool_def.include_return_schema,
- )
+ async def prepare_tool_definition(_ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition:
+ return replace(tool_def, parameters_json_schema=tool_schema, strict=CORE_TOOL_STRICT)
return Tool(
invoke_tool,
@@ -161,4 +129,4 @@ def _tool_error_text(*, tool_name: str, error: DifyCoreToolsClientError) -> str:
return f"tool invoke error: {error}"
-__all__ = ["DifyCoreToolsDeps", "DifyCoreToolsLayer"]
+__all__ = ["Config", "State", "Toolset"]
diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py b/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py
index bd719cea8f5..138f0d78c21 100644
--- a/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py
+++ b/dify-agent/src/dify_agent/layers/dify_plugin/__init__.py
@@ -5,8 +5,6 @@ dependencies. Keep this package root import-safe for client-only installs.
"""
from dify_agent.layers.dify_plugin.configs import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
DifyPluginCredentialValue,
DifyPluginLLMLayerConfig,
DifyPluginToolCredentialType,
@@ -20,8 +18,6 @@ from dify_agent.layers.dify_plugin.configs import (
)
__all__ = [
- "DIFY_PLUGIN_LLM_LAYER_TYPE_ID",
- "DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID",
"DifyPluginCredentialValue",
"DifyPluginLLMLayerConfig",
"DifyPluginToolCredentialType",
diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/configs.py b/dify-agent/src/dify_agent/layers/dify_plugin/configs.py
index ad289c055d8..8c81467ad07 100644
--- a/dify-agent/src/dify_agent/layers/dify_plugin/configs.py
+++ b/dify-agent/src/dify_agent/layers/dify_plugin/configs.py
@@ -1,4 +1,4 @@
-"""Client-safe DTOs for Dify plugin-backed Agenton business layers.
+"""Client-safe DTOs for Dify plugin-backed business layers.
This module intentionally contains only public config schemas and scalar type
aliases plus stable plugin business-layer type identifiers. Runtime objects
@@ -15,19 +15,15 @@ re-fetch and re-merge tool declarations at execution time.
"""
from enum import StrEnum
-from typing import ClassVar, Final, Literal, TypeAlias
+from typing import ClassVar, Literal, TypeAlias
from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator
from pydantic_ai.settings import ModelSettings
-from agenton.layers import LayerConfig
-
DifyPluginCredentialValue: TypeAlias = str | int | float | bool | None
DifyPluginToolCredentialType: TypeAlias = Literal["api-key", "oauth2", "unauthorized"]
DifyPluginToolValue: TypeAlias = JsonValue
-DIFY_PLUGIN_LLM_LAYER_TYPE_ID: Final[str] = "dify.plugin.llm"
-DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID: Final[str] = "dify.plugin.tools"
def _default_parameters_json_schema() -> dict[str, JsonValue]:
@@ -106,9 +102,11 @@ class DifyPluginToolParameter(BaseModel):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="ignore", from_attributes=True)
-class DifyPluginLLMLayerConfig(LayerConfig):
+class DifyPluginLLMLayerConfig(BaseModel):
"""Public config for selecting a plugin-backed business provider/model."""
+ execution_context: str = "execution_context"
+
plugin_id: str
model_provider: str
model: str
@@ -127,7 +125,7 @@ class DifyPluginLLMLayerConfig(LayerConfig):
return value
-class DifyPluginToolConfig(LayerConfig):
+class DifyPluginToolConfig(BaseModel):
"""Public config for exposing one plugin tool to the agent model.
``credential_type`` is an explicit caller-supplied daemon transport choice,
@@ -160,21 +158,22 @@ class DifyPluginToolConfig(LayerConfig):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
-class DifyPluginToolsLayerConfig(LayerConfig):
+class DifyPluginToolsLayerConfig(BaseModel):
"""Public config for the Dify plugin tools layer.
Callers configure the tools layer with this wrapper object and supply one
or more prepared ``DifyPluginToolConfig`` entries in ``tools``.
"""
+ execution_context: str = "execution_context"
+ shell: str | None = None
+
tools: list[DifyPluginToolConfig] = Field(default_factory=list)
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
__all__ = [
- "DIFY_PLUGIN_LLM_LAYER_TYPE_ID",
- "DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID",
"DifyPluginCredentialValue",
"DifyPluginLLMLayerConfig",
"DifyPluginToolCredentialType",
diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py b/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py
index 71e26f22b9e..9ceb79839ef 100644
--- a/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py
+++ b/dify-agent/src/dify_agent/layers/dify_plugin/llm_layer.py
@@ -1,77 +1,42 @@
-"""Dify plugin LLM model layer.
+"""Construct the API-metered model from JSON config and borrowed services."""
-This layer owns model capability resolution for Dify plugin-backed LLMs. It
-depends on ``DifyExecutionContextLayer`` for shared request context through
-Agenton's direct dependency binding and returns a Pydantic AI model adapter
-configured from the public LLM layer DTO. Runtime code supplies the FastAPI
-lifespan-owned shared HTTP client to ``get_model``; the layer does not own or
-discover live resources. The API provider carries plugin transport identity,
-while the DTO's ``model_provider`` is passed to the adapter as request-level
-model identity.
-"""
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai.capabilities import AbstractCapability
-from dataclasses import dataclass, field
-from typing import ClassVar
-
-import httpx
-from typing_extensions import Self, override
-
-from agenton.layers import LayerDeps, PlainLayer
from dify_agent.adapters.llm import DifyApiLLMProvider, DifyLLMAdapterModel
-from dify_agent.layers.dify_plugin.configs import DIFY_PLUGIN_LLM_LAYER_TYPE_ID, DifyPluginLLMLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-
-
-class DifyPluginLLMDeps(LayerDeps):
- """Dependencies required by ``DifyPluginLLMLayer``."""
+from dify_agent.layers.dify_plugin.configs import DifyPluginLLMLayerConfig
+from dify_agent.layers.execution_context.layer import Config as ExecutionContextConfig
+from dify_agent.runtime.context import Deps
- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]
+class Config(DifyPluginLLMLayerConfig):
+ pass
-@dataclass(slots=True)
-class DifyPluginLLMLayer(PlainLayer[DifyPluginLLMDeps, DifyPluginLLMLayerConfig]):
- """Layer that creates the Dify API-backed Pydantic AI model."""
- type_id: ClassVar[str | None] = DIFY_PLUGIN_LLM_LAYER_TYPE_ID
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
- config: DifyPluginLLMLayerConfig
- inner_api_url: str = "http://localhost:5001"
- inner_api_key: str = field(default="", repr=False)
- @classmethod
- @override
- def from_config(cls, config: DifyPluginLLMLayerConfig) -> Self:
- """Create the LLM layer from validated public config."""
- return cls(config=config)
+class Capability(AbstractCapability[Deps]):
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
- @classmethod
- def from_config_with_settings(
- cls,
- config: DifyPluginLLMLayerConfig,
- *,
- inner_api_url: str,
- inner_api_key: str,
- ) -> Self:
- return cls(config=config, inner_api_url=inner_api_url.rstrip("/"), inner_api_key=inner_api_key)
-
- def get_model(self, *, http_client: httpx.AsyncClient, agent_run_id: str) -> DifyLLMAdapterModel:
- """Return the configured model through the API-owned metered gateway."""
- if http_client.is_closed:
- raise RuntimeError("DifyPluginLLMLayer.get_model() requires an open Dify API HTTP client.")
+ def build_model(self, deps: Deps) -> DifyLLMAdapterModel:
+ config = Config.model_validate(deps.layers[self.name]["config"])
+ if deps.services.dify_api_http_client.is_closed:
+ raise RuntimeError("Model execution requires an open Dify API HTTP client.")
provider = DifyApiLLMProvider(
- plugin_id=self.config.plugin_id,
- inner_api_url=self.inner_api_url,
- inner_api_key=self.inner_api_key,
- execution_context=self.deps.execution_context.config,
- agent_run_id=agent_run_id,
- http_client=http_client,
+ plugin_id=config.plugin_id,
+ inner_api_url=deps.services.inner_api_url,
+ inner_api_key=deps.services.inner_api_key,
+ execution_context=ExecutionContextConfig.model_validate(deps.layers[config.execution_context]["config"]),
+ agent_run_id=deps.run_id,
+ http_client=deps.services.dify_api_http_client,
)
return DifyLLMAdapterModel(
- model=self.config.model,
+ model=config.model,
dify_provider=provider,
- model_provider=self.config.model_provider,
- model_settings=self.config.model_settings,
+ model_provider=config.model_provider,
+ model_settings=config.model_settings,
)
-
-
-__all__ = ["DifyPluginLLMDeps", "DifyPluginLLMLayer"]
diff --git a/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py b/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py
index 6e43566e589..f48cc948114 100644
--- a/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py
+++ b/dify-agent/src/dify_agent/layers/dify_plugin/tools_layer.py
@@ -17,19 +17,18 @@ from copy import deepcopy
import json
import mimetypes
from collections.abc import Mapping, Sequence
-from dataclasses import dataclass, field
-from typing import ClassVar
+from dataclasses import dataclass, field, replace
+from typing import ClassVar, override
from urllib.parse import urlparse
import httpx
from pydantic import BaseModel, ConfigDict, JsonValue, ValidationError
from pydantic_ai import RunContext, Tool
from pydantic_ai.tools import ToolDefinition
-from typing_extensions import Self, override
-from agenton.layers import LayerDeps, PlainLayer
+from pydantic_ai.toolsets import FunctionToolset
+from dify_agent.runtime.context import Deps
from dify_agent.layers.dify_plugin.configs import (
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
DifyPluginToolConfig,
DifyPluginToolParameter,
DifyPluginToolParameterForm,
@@ -42,8 +41,7 @@ from dify_agent.layers.dify_plugin.tool_client import (
DifyPluginToolInvokeMessage,
)
from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-from dify_agent.layers.shell.layer import DifyShellLayer
+from dify_agent.layers.execution_context.layer import Capability as ExecutionContextCapability
# Plugin tools intentionally do not expose a per-tool strictness override in the
@@ -58,13 +56,6 @@ _FILE_UPLOAD_TIMEOUT_SECONDS = 60.0
_SUPPORTED_REMOTE_URL_PREFIXES = ("http://", "https://")
-class DifyPluginToolsDeps(LayerDeps):
- """Dependencies required by ``DifyPluginToolsLayer``."""
-
- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]
- shell: DifyShellLayer | None # pyright: ignore[reportUninitializedInstanceVariable]
-
-
class DifyPluginToolsClientConfigurationError(ValueError):
"""Raised when local plugin-tool file conversion preconditions are missing."""
@@ -154,81 +145,64 @@ class _DifyPluginToolFileClient:
raise DifyPluginToolClientError("Invalid Dify API file download data.") from exc
-@dataclass(slots=True)
-class DifyPluginToolsLayer(PlainLayer[DifyPluginToolsDeps, DifyPluginToolsLayerConfig]):
- """Layer that resolves Dify plugin tools into Pydantic AI tools."""
+class Config(DifyPluginToolsLayerConfig):
+ pass
- type_id: ClassVar[str | None] = DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID
- config: DifyPluginToolsLayerConfig
- inner_api_url: str
- inner_api_key: str
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
- @classmethod
- @override
- def from_config(cls, config: DifyPluginToolsLayerConfig) -> Self:
- """Reject construction without server-injected Dify API settings."""
- del config
- raise TypeError("DifyPluginToolsLayer requires server-side Dify API settings and must use a provider factory.")
-
- @classmethod
- def from_config_with_settings(
- cls,
- config: DifyPluginToolsLayerConfig,
- *,
- inner_api_url: str,
- inner_api_key: str,
- ) -> Self:
- return cls(
- config=DifyPluginToolsLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- )
- async def get_tools(
- self,
- *,
- http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- """Build Pydantic AI tool adapters from prepared plugin tool config."""
- if dify_api_http_client.is_closed:
- raise RuntimeError("DifyPluginToolsLayer.get_tools() requires an open shared Dify API HTTP client.")
-
- tool_clients: dict[str, DifyPluginDaemonToolClient] = {}
- tools: list[Tool[object]] = []
- file_client = _DifyPluginToolFileClient(
- base_url=self.inner_api_url,
- api_key=self.inner_api_key,
- http_client=dify_api_http_client,
- )
- file_context = _PluginToolFileContext(
- file_client=file_client,
- execution_context=self.deps.execution_context.config,
- shell=self.deps.shell,
- )
+class Toolset(FunctionToolset[Deps]):
+ """Prepare native tools once per run; all clients and shell resources are borrowed."""
- for tool_config in self.config.tools:
- client = tool_clients.get(tool_config.plugin_id)
- if client is None:
- client = self.deps.execution_context.create_tool_client(
- plugin_id=tool_config.plugin_id,
- http_client=http_client,
- )
- tool_clients[tool_config.plugin_id] = client
- effective_parameters = [parameter.model_copy(deep=True) for parameter in tool_config.parameters]
- _validate_required_hidden_parameters(tool_config, effective_parameters)
-
- tools.append(
- _build_pydantic_ai_tool(
- client=client,
- tool_config=tool_config,
- effective_parameters=effective_parameters,
- file_context=file_context,
- )
- )
+ def __init__(self, name: str):
+ super().__init__(id=name)
+ self.name = name
+ self._loaded = False
- return tools
+ @override
+ async def get_tools(self, ctx: RunContext[Deps]):
+ if not self._loaded:
+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])
+ services = ctx.deps.services
+ if services.dify_api_http_client.is_closed:
+ raise RuntimeError("Plugin tools require an open shared Dify API HTTP client.")
+ tool_clients: dict[str, DifyPluginDaemonToolClient] = {}
+ file_context = _PluginToolFileContext(
+ file_client=_DifyPluginToolFileClient(
+ base_url=services.inner_api_url,
+ api_key=services.inner_api_key,
+ http_client=services.dify_api_http_client,
+ ),
+ execution_context=DifyExecutionContextLayerConfig.model_validate(
+ ctx.deps.layers[config.execution_context]["config"]
+ ),
+ deps=ctx.deps,
+ shell=config.shell,
+ )
+ for tool_config in config.tools:
+ client = tool_clients.get(tool_config.plugin_id)
+ if client is None:
+ client = ExecutionContextCapability.create_tool_client(
+ ctx.deps,
+ config.execution_context,
+ plugin_id=tool_config.plugin_id,
+ http_client=services.plugin_daemon_http_client,
+ )
+ tool_clients[tool_config.plugin_id] = client
+ effective_parameters = [parameter.model_copy(deep=True) for parameter in tool_config.parameters]
+ _validate_required_hidden_parameters(tool_config, effective_parameters)
+ self.add_tool(
+ _build_pydantic_ai_tool(
+ client=client,
+ tool_config=tool_config,
+ effective_parameters=effective_parameters,
+ file_context=file_context,
+ )
+ )
+ self._loaded = True
+ return await super().get_tools(ctx)
def _validate_required_hidden_parameters(
@@ -254,12 +228,12 @@ def _build_pydantic_ai_tool(
tool_config: DifyPluginToolConfig,
effective_parameters: Sequence[DifyPluginToolParameter],
file_context: "_PluginToolFileContext",
-) -> Tool[object]:
+) -> Tool[Deps]:
tool_name = tool_config.name or tool_config.tool_name
tool_description = tool_config.description or tool_name
tool_schema = deepcopy(tool_config.parameters_json_schema)
- async def invoke_tool(_ctx: RunContext[object], **tool_arguments: object) -> str:
+ async def invoke_tool(_ctx: RunContext[Deps], **tool_arguments: object) -> str:
try:
merged_arguments = await _prepare_tool_arguments(
effective_parameters,
@@ -280,20 +254,8 @@ def _build_pydantic_ai_tool(
except ValueError as exc:
return f"tool parameters validation error: {exc}, please check your tool parameters"
- async def prepare_tool_definition(_ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:
- return ToolDefinition(
- name=tool_def.name,
- description=tool_def.description,
- parameters_json_schema=tool_schema,
- strict=PLUGIN_TOOL_STRICT,
- sequential=tool_def.sequential,
- metadata=tool_def.metadata,
- timeout=tool_def.timeout,
- defer_loading=tool_def.defer_loading,
- kind=tool_def.kind,
- return_schema=tool_def.return_schema,
- include_return_schema=tool_def.include_return_schema,
- )
+ async def prepare_tool_definition(_ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition:
+ return replace(tool_def, parameters_json_schema=tool_schema, strict=PLUGIN_TOOL_STRICT)
return Tool(
invoke_tool,
@@ -352,7 +314,8 @@ async def _prepare_tool_arguments(
class _PluginToolFileContext:
file_client: _DifyPluginToolFileClient
execution_context: DifyExecutionContextLayerConfig
- shell: DifyShellLayer | None
+ deps: Deps
+ shell: str | None
async def to_plugin_file_parameter(self, value: object) -> dict[str, object]:
if isinstance(value, str):
@@ -389,7 +352,7 @@ class _PluginToolFileContext:
f"print('{_FILE_UPLOAD_BEGIN}' + json.dumps(payload, separators=(',', ':')) + '{_FILE_UPLOAD_END}')\n"
"PY"
)
- result = await self.shell.run_remote_script_complete(
+ result = await self.deps.resources.shells[self.shell].run_remote_script_complete(
script,
timeout=_FILE_UPLOAD_TIMEOUT_SECONDS,
inject_agent_stub_env=True,
@@ -678,4 +641,4 @@ def _convert_tool_response_to_text(tool_response: Sequence[DifyPluginToolInvokeM
return "".join(parts)
-__all__ = ["DifyPluginToolsDeps", "DifyPluginToolsLayer"]
+__all__ = ["Config", "State", "Toolset"]
diff --git a/dify-agent/src/dify_agent/layers/execution_context/__init__.py b/dify-agent/src/dify_agent/layers/execution_context/__init__.py
index 45575faf3e2..356653ae65c 100644
--- a/dify-agent/src/dify_agent/layers/execution_context/__init__.py
+++ b/dify-agent/src/dify_agent/layers/execution_context/__init__.py
@@ -7,7 +7,6 @@ DTO, but that runtime implementation still lives in sibling modules.
"""
from dify_agent.layers.execution_context.configs import (
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
DifyExecutionContextAgentConfigVersionKind,
DifyExecutionContextAgentMode,
DifyExecutionContextInvokeFrom,
@@ -16,7 +15,6 @@ from dify_agent.layers.execution_context.configs import (
)
__all__ = [
- "DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID",
"DifyExecutionContextAgentConfigVersionKind",
"DifyExecutionContextAgentMode",
"DifyExecutionContextInvokeFrom",
diff --git a/dify-agent/src/dify_agent/layers/execution_context/configs.py b/dify-agent/src/dify_agent/layers/execution_context/configs.py
index afddd7b9344..1f8d1d51453 100644
--- a/dify-agent/src/dify_agent/layers/execution_context/configs.py
+++ b/dify-agent/src/dify_agent/layers/execution_context/configs.py
@@ -1,4 +1,4 @@
-"""Client-safe DTOs for the Dify execution-context Agenton layer.
+"""Client-safe DTOs for the Dify execution-context layer.
This layer carries both Dify product execution context (tenant, user, workflow,
invoke source) and Agent backend runtime mode. The product-facing fields are
@@ -7,18 +7,15 @@ need to reconstruct Dify API file-access scope without granting the sandbox any
direct inner-API credentials. Knowledge-base layers also read ``user_from`` from
this shared config so the inner Dify API can distinguish platform-user and
end-user searches without making that caller identity model-controlled.
-Server-only plugin-daemon settings are injected by the runtime provider factory
+Server-only plugin-daemon settings are injected by the runtime runtime services
and therefore do not appear in this public schema.
"""
-from typing import ClassVar, Final, Literal, TypeAlias
+from typing import ClassVar, Literal, TypeAlias
-from pydantic import ConfigDict
+from pydantic import BaseModel, ConfigDict
-from agenton.layers import LayerConfig
-
-DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID: Final[str] = "dify.execution_context"
DifyExecutionContextAgentMode: TypeAlias = Literal[
"workflow_run",
"single_step",
@@ -40,7 +37,7 @@ DifyExecutionContextInvokeFrom: TypeAlias = Literal[
]
-class DifyExecutionContextLayerConfig(LayerConfig):
+class DifyExecutionContextLayerConfig(BaseModel):
"""Public config for Dify execution identity and daemon transport context."""
tenant_id: str
@@ -63,7 +60,6 @@ class DifyExecutionContextLayerConfig(LayerConfig):
__all__ = [
- "DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID",
"DifyExecutionContextAgentConfigVersionKind",
"DifyExecutionContextAgentMode",
"DifyExecutionContextInvokeFrom",
diff --git a/dify-agent/src/dify_agent/layers/execution_context/layer.py b/dify-agent/src/dify_agent/layers/execution_context/layer.py
index 2e4b726bcda..831ff1f3a89 100644
--- a/dify-agent/src/dify_agent/layers/execution_context/layer.py
+++ b/dify-agent/src/dify_agent/layers/execution_context/layer.py
@@ -1,75 +1,39 @@
-"""Runtime Dify execution-context layer.
-
-The public config carries Dify-owned execution identifiers plus the tenant/user
-daemon context needed by plugin-backed business layers and the caller identity
-needed by knowledge-base layers. Server-only daemon URL
-and API key are injected by the provider factory. The layer is intentionally
-config/settings-only under Agenton's state-only core: it does not open, cache,
-close, or snapshot HTTP clients, and its lifecycle hooks remain the inherited
-no-op hooks. Runtime code passes the FastAPI lifespan-owned shared
-``httpx.AsyncClient`` into ``create_tool_client`` for each tool invocation.
-"""
-
-from dataclasses import dataclass
-from typing import ClassVar
+"""Dify identity module; clients and transport settings remain lifespan-owned."""
import httpx
-from typing_extensions import Self, override
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai.capabilities import AbstractCapability
-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PlainLayer
+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
from dify_agent.layers.dify_plugin.tool_client import DifyPluginDaemonToolClient
-from dify_agent.layers.execution_context.configs import (
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- DifyExecutionContextLayerConfig,
-)
-
+from dify_agent.runtime.context import Deps
-@dataclass(slots=True)
-class DifyExecutionContextLayer(PlainLayer[NoLayerDeps, DifyExecutionContextLayerConfig, EmptyRuntimeState]):
- """Layer that carries Dify execution context without owning live resources."""
- type_id: ClassVar[str | None] = DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID
+class Config(DifyExecutionContextLayerConfig):
+ pass
- config: DifyExecutionContextLayerConfig
- daemon_url: str
- daemon_api_key: str
- @classmethod
- @override
- def from_config(cls, config: DifyExecutionContextLayerConfig) -> Self:
- """Reject construction without server-injected daemon settings."""
- del config
- raise TypeError(
- "DifyExecutionContextLayer requires server-side daemon settings and must use a provider factory."
- )
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
- @classmethod
- def from_config_with_settings(
- cls,
- config: DifyExecutionContextLayerConfig,
- *,
- daemon_url: str,
- daemon_api_key: str,
- ) -> Self:
- """Create the layer from public config plus server-only daemon settings."""
- return cls(config=config, daemon_url=daemon_url, daemon_api_key=daemon_api_key)
- def create_tool_client(self, *, plugin_id: str, http_client: httpx.AsyncClient) -> DifyPluginDaemonToolClient:
- """Return a plugin-daemon tool client backed by the shared HTTP client.
+class Capability(AbstractCapability[Deps]):
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
- Raises:
- RuntimeError: if ``http_client`` has already been closed.
- """
+ @staticmethod
+ def create_tool_client(
+ deps: Deps, name: str, *, plugin_id: str, http_client: httpx.AsyncClient
+ ) -> DifyPluginDaemonToolClient:
if http_client.is_closed:
- raise RuntimeError("DifyExecutionContextLayer.create_tool_client() requires an open shared HTTP client.")
+ raise RuntimeError("Plugin tool invocation requires an open shared HTTP client.")
+ config = Config.model_validate(deps.layers[name]["config"])
return DifyPluginDaemonToolClient(
- tenant_id=self.config.tenant_id,
+ tenant_id=config.tenant_id,
plugin_id=plugin_id,
- plugin_daemon_url=self.daemon_url,
- plugin_daemon_api_key=self.daemon_api_key,
- user_id=self.config.user_id,
+ plugin_daemon_url=deps.services.plugin_daemon_url,
+ plugin_daemon_api_key=deps.services.plugin_daemon_api_key,
+ user_id=config.user_id,
http_client=http_client,
)
-
-
-__all__ = ["DifyExecutionContextLayer"]
diff --git a/dify-agent/src/dify_agent/layers/history.py b/dify-agent/src/dify_agent/layers/history.py
new file mode 100644
index 00000000000..5c7d09d6beb
--- /dev/null
+++ b/dify-agent/src/dify_agent/layers/history.py
@@ -0,0 +1,41 @@
+"""Conversation persistence in JSON state; run instructions remain transient."""
+
+from collections.abc import Sequence
+from dataclasses import replace
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse
+
+from dify_agent.runtime.context import Deps
+
+
+class Config(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+
+
+class State(BaseModel):
+ messages: list[ModelMessage] = Field(default_factory=list)
+ model_config = ConfigDict(extra="forbid")
+
+
+class Capability(AbstractCapability[Deps]):
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
+
+ def load_messages(self, deps: Deps) -> list[ModelMessage]:
+ return State.model_validate(deps.layers[self.name]["state"]).messages
+
+ def save_messages(self, deps: Deps, messages: Sequence[ModelMessage], *, interrupted: bool = False) -> None:
+ """Save captured history, closing unexecuted trailing calls on interruption.
+
+ Pydantic AI closes unmatched tool calls on the next user turn when a response
+ is marked interrupted, rather than complete.
+ """
+ persistent = [replace(m, instructions=None) if isinstance(m, ModelRequest) else m for m in messages]
+ if interrupted and persistent:
+ last = persistent[-1]
+ if isinstance(last, ModelResponse) and last.state == "complete" and last.tool_calls:
+ persistent[-1] = replace(last, state="interrupted")
+ deps.layers[self.name]["state"] = State(messages=persistent).model_dump(mode="json")
diff --git a/dify-agent/src/dify_agent/layers/knowledge/__init__.py b/dify-agent/src/dify_agent/layers/knowledge/__init__.py
index 86a9405bce3..d25893606c1 100644
--- a/dify-agent/src/dify_agent/layers/knowledge/__init__.py
+++ b/dify-agent/src/dify_agent/layers/knowledge/__init__.py
@@ -5,7 +5,6 @@ root stays import-safe for callers that only need to construct run requests.
"""
from dify_agent.layers.knowledge.configs import (
- DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
DifyKnowledgeBaseLayerConfig,
DifyKnowledgeDatasetConfig,
DifyKnowledgeEagerResult,
@@ -21,7 +20,6 @@ from dify_agent.layers.knowledge.configs import (
)
__all__ = [
- "DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID",
"DifyKnowledgeBaseLayerConfig",
"DifyKnowledgeDatasetConfig",
"DifyKnowledgeEagerResult",
diff --git a/dify-agent/src/dify_agent/layers/knowledge/configs.py b/dify-agent/src/dify_agent/layers/knowledge/configs.py
index b7b71ab9c42..36386b50e5f 100644
--- a/dify-agent/src/dify_agent/layers/knowledge/configs.py
+++ b/dify-agent/src/dify_agent/layers/knowledge/configs.py
@@ -1,4 +1,4 @@
-"""Client-safe DTOs for the Dify knowledge-base Agenton layer.
+"""Client-safe DTOs for the Dify knowledge-base layer.
The public layer config carries one or more named knowledge sets. Each set owns
its dataset ids plus query, retrieval, and metadata-filtering policy. Generated-
@@ -10,11 +10,10 @@ are kept only in JSON-safe ``runtime_state`` for session snapshots.
from __future__ import annotations
-from typing import ClassVar, Final, Literal
+from typing import ClassVar, Literal
from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_validator, model_validator
-from agenton.layers import LayerConfig
type DifyKnowledgeMetadataComparisonOperator = Literal[
"contains",
@@ -37,8 +36,6 @@ type DifyKnowledgeMetadataComparisonOperator = Literal[
"after",
]
-DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID: Final[str] = "dify.knowledge_base"
-
class DifyKnowledgeModelConfig(BaseModel):
"""Static model configuration forwarded to the inner retrieval API."""
@@ -239,7 +236,7 @@ class DifyKnowledgeEagerResult(BaseModel):
class DifyKnowledgeRuntimeState(BaseModel):
- """Serializable eager-retrieval state stored in Agenton session snapshots."""
+ """Serializable eager-retrieval state stored in session snapshots."""
eager_config_fingerprint: str | None = None
eager_results: list[DifyKnowledgeEagerResult] = Field(default_factory=list)
@@ -247,7 +244,7 @@ class DifyKnowledgeRuntimeState(BaseModel):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid", validate_assignment=True)
-class DifyKnowledgeBaseLayerConfig(LayerConfig):
+class DifyKnowledgeBaseLayerConfig(BaseModel):
"""Public config for one knowledge-base layer.
The model-visible surface stays fixed to ``knowledge_base_search``. Set
@@ -256,6 +253,8 @@ class DifyKnowledgeBaseLayerConfig(LayerConfig):
concerns outside the tool schema.
"""
+ execution_context: str = "execution_context"
+
sets: list[DifyKnowledgeSetConfig]
max_result_content_chars: int = Field(default=2000, ge=1)
max_observation_chars: int = Field(default=12000, ge=1)
@@ -278,7 +277,6 @@ class DifyKnowledgeBaseLayerConfig(LayerConfig):
__all__ = [
- "DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID",
"DifyKnowledgeBaseLayerConfig",
"DifyKnowledgeDatasetConfig",
"DifyKnowledgeEagerResult",
diff --git a/dify-agent/src/dify_agent/layers/knowledge/layer.py b/dify-agent/src/dify_agent/layers/knowledge/layer.py
index ed1005e40ae..1bd6433ed80 100644
--- a/dify-agent/src/dify_agent/layers/knowledge/layer.py
+++ b/dify-agent/src/dify_agent/layers/knowledge/layer.py
@@ -1,35 +1,39 @@
"""Dify knowledge-base layer exposing set-aware retrieval.
-The layer depends on ``DifyExecutionContextLayer`` for tenant/app/user/invoke
+The layer depends on ``execution-context Config`` for tenant/app/user/invoke
identity. Generated-query sets become one stable model-visible
``knowledge_base_search(set_name, query)`` tool, while user-query sets are
retrieved eagerly during context entry and exposed as additional user prompt
content. Eager observations are persisted only as JSON-safe runtime state so
-Agenton session snapshots can resume without repeating unchanged retrievals.
+session snapshots can resume without repeating unchanged retrievals.
"""
from __future__ import annotations
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
import hashlib
import json
import logging
-from typing import ClassVar, cast
+from typing import cast, override
import httpx
from pydantic_ai import RunContext, Tool
from pydantic_ai.tools import ToolDefinition
-from typing_extensions import Self, override
-from agenton.layers import LayerDeps, PlainLayer
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.capabilities.abstract import WrapRunHandler
+from pydantic_ai.run import AgentRunResult
+from pydantic_ai.toolsets import FunctionToolset
+from pydantic_ai.models import ModelRequestContext
+from pydantic_ai.messages import ModelRequest, UserPromptPart
+from dify_agent.runtime.context import Deps
+from dify_agent.layers.execution_context.layer import Config as ExecutionContextConfig
from dify_agent.layers.knowledge.client import (
DifyKnowledgeBaseClient,
DifyKnowledgeBaseClientError,
DifyKnowledgeRetrieveResponse,
)
from dify_agent.layers.knowledge.configs import (
- DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
DifyKnowledgeBaseLayerConfig,
DifyKnowledgeEagerResult,
DifyKnowledgeRuntimeState,
@@ -52,49 +56,94 @@ TEMPORARY_UNAVAILABLE_OBSERVATION = (
)
-class DifyKnowledgeBaseDeps(LayerDeps):
- """Dependencies required by ``DifyKnowledgeBaseLayer``."""
+class Config(DifyKnowledgeBaseLayerConfig):
+ pass
- execution_context: DifyExecutionContextLayer # pyright: ignore[reportUninitializedInstanceVariable]
+class State(DifyKnowledgeRuntimeState):
+ pass
-@dataclass(slots=True)
-class DifyKnowledgeBaseLayer(
- PlainLayer[DifyKnowledgeBaseDeps, DifyKnowledgeBaseLayerConfig, DifyKnowledgeRuntimeState]
-):
- """Layer that resolves set-scoped knowledge tools and eager user prompts."""
- type_id: ClassVar[str | None] = DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID
+class Capability(AbstractCapability[Deps]):
+ """Eager retrieval and user-context injection plus generated-query tools."""
- config: DifyKnowledgeBaseLayerConfig
- inner_api_url: str
- inner_api_key: str
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
+ self._injected = False
- @classmethod
@override
- def from_config(cls, config: DifyKnowledgeBaseLayerConfig) -> Self:
- """Reject construction without server-injected Dify API settings."""
- del config
- raise TypeError(
- "DifyKnowledgeBaseLayer requires server-side Dify API settings and must use a provider factory."
- )
+ def get_toolset(self) -> FunctionToolset[Deps]:
+ return _KnowledgeTools(self.name)
- @classmethod
- def from_config_with_settings(
- cls,
- config: DifyKnowledgeBaseLayerConfig,
- *,
- inner_api_url: str,
- inner_api_key: str,
- ) -> Self:
- """Create the layer from public config plus server-only API settings."""
- return cls(
- config=DifyKnowledgeBaseLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- )
+ def provides_user_content(self, deps: Deps) -> bool:
+ """User-query retrieval supplies meaningful user input before the model."""
+ config = Config.model_validate(deps.layers[self.name]["config"])
+ return any(knowledge_set.query.mode == "user_query" for knowledge_set in config.sets)
+
+ @override
+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:
+ await _KnowledgeOperations(self.name, ctx.deps)._refresh_eager_results_if_needed()
+ return await handler()
+
+ @override
+ async def before_model_request(
+ self, ctx: RunContext[Deps], request_context: ModelRequestContext
+ ) -> ModelRequestContext:
+ if not self._injected and ctx.prompt is not None:
+ self._injected = True
+ prompts = _KnowledgeOperations(self.name, ctx.deps).user_prompts
+ if prompts:
+ # Keep retrieval in the user role and in captured conversation history.
+ request_context.messages.append(ModelRequest(parts=[UserPromptPart(content="\n\n".join(prompts))]))
+ return request_context
+
+
+class _KnowledgeTools(FunctionToolset[Deps]):
+ def __init__(self, name: str):
+ super().__init__(id=name)
+ self.name = name
+ self._loaded = False
- async def get_tools(self, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:
+ @override
+ async def get_tools(self, ctx: RunContext[Deps]):
+ if not self._loaded:
+ for tool in await _KnowledgeOperations(self.name, ctx.deps).build_tools(
+ http_client=ctx.deps.services.dify_api_http_client
+ ):
+ self.add_tool(tool)
+ self._loaded = True
+ return await super().get_tools(ctx)
+
+
+@dataclass
+class _KnowledgeOperations:
+ """Request-scoped retrieval operations; JSON holds all cached state."""
+
+ name: str
+ deps: Deps
+
+ @property
+ def config(self) -> Config:
+ return Config.model_validate(self.deps.layers[self.name]["config"])
+
+ @property
+ def runtime_state(self) -> State:
+ return State.model_validate(self.deps.layers[self.name]["state"])
+
+ @property
+ def execution_context(self) -> ExecutionContextConfig:
+ return ExecutionContextConfig.model_validate(self.deps.layers[self.config.execution_context]["config"])
+
+ @property
+ def inner_api_url(self) -> str:
+ return self.deps.services.inner_api_url
+
+ @property
+ def inner_api_key(self) -> str:
+ return self.deps.services.inner_api_key
+
+ async def build_tools(self, *, http_client: httpx.AsyncClient) -> list[Tool[Deps]]:
"""Build the unified generated-query Pydantic AI tool, when needed.
Knowledge tools depend on execution-context identity that is optional for
@@ -115,7 +164,7 @@ class DifyKnowledgeBaseLayer(
if http_client.is_closed:
raise RuntimeError("DifyKnowledgeBaseLayer.get_tools() requires an open shared HTTP client.")
- execution_context = self.deps.execution_context.config
+ execution_context = self.execution_context
caller = _build_caller_context(execution_context)
client = DifyKnowledgeBaseClient(
base_url=self.inner_api_url,
@@ -124,7 +173,7 @@ class DifyKnowledgeBaseLayer(
)
set_by_name = {knowledge_set.name: knowledge_set for knowledge_set in generated_sets}
- async def knowledge_base_search(_ctx: RunContext[object], set_name: str, query: str) -> str:
+ async def knowledge_base_search(_ctx: RunContext[Deps], set_name: str, query: str) -> str:
knowledge_set = set_by_name.get(set_name)
if knowledge_set is None:
return f"unknown knowledge set: {set_name}"
@@ -139,20 +188,8 @@ class DifyKnowledgeBaseLayer(
retryable_observation=True,
)
- async def prepare_tool_definition(_ctx: RunContext[object], tool_def: ToolDefinition) -> ToolDefinition:
- return ToolDefinition(
- name=tool_def.name,
- description=tool_def.description,
- parameters_json_schema=_tool_schema(generated_sets),
- strict=tool_def.strict,
- sequential=tool_def.sequential,
- metadata=tool_def.metadata,
- timeout=tool_def.timeout,
- defer_loading=tool_def.defer_loading,
- kind=tool_def.kind,
- return_schema=tool_def.return_schema,
- include_return_schema=tool_def.include_return_schema,
- )
+ async def prepare_tool_definition(_ctx: RunContext[Deps], tool_def: ToolDefinition) -> ToolDefinition:
+ return replace(tool_def, parameters_json_schema=_tool_schema(generated_sets))
return [
Tool(
@@ -165,7 +202,6 @@ class DifyKnowledgeBaseLayer(
]
@property
- @override
def user_prompts(self) -> list[str]:
"""Expose eager user-query results as an additional user prompt."""
if not self.runtime_state.eager_results:
@@ -185,14 +221,6 @@ class DifyKnowledgeBaseLayer(
)
return ["Knowledge retrieval results:\n\n" + "\n\n".join(sections)]
- @override
- async def on_context_create(self) -> None:
- await self._refresh_eager_results_if_needed()
-
- @override
- async def on_context_resume(self) -> None:
- await self._refresh_eager_results_if_needed()
-
def _generated_query_sets(self) -> list[DifyKnowledgeSetConfig]:
return [knowledge_set for knowledge_set in self.config.sets if knowledge_set.query.mode == "generated_query"]
@@ -202,63 +230,38 @@ class DifyKnowledgeBaseLayer(
async def _refresh_eager_results_if_needed(self) -> None:
user_query_sets = self._user_query_sets()
if not user_query_sets:
- self.runtime_state.eager_config_fingerprint = None
- self.runtime_state.eager_results = []
+ self.deps.layers[self.name]["state"] = State().model_dump(mode="json")
return
fingerprint = _eager_config_fingerprint(user_query_sets)
if self.runtime_state.eager_config_fingerprint == fingerprint:
return
- caller = _build_caller_context(self.deps.execution_context.config)
- async with httpx.AsyncClient() as http_client:
- client = DifyKnowledgeBaseClient(
- base_url=self.inner_api_url,
- api_key=self.inner_api_key,
- http_client=http_client,
- )
- eager_results: list[DifyKnowledgeEagerResult] = []
- for knowledge_set in user_query_sets:
- query = (knowledge_set.query.value or "").strip()
- try:
- response = await client.retrieve(
- tenant_id=caller["tenant_id"],
- user_id=caller["user_id"],
- app_id=caller["app_id"],
- user_from=caller["user_from"],
- invoke_from=caller["invoke_from"],
- dataset_ids=knowledge_set.dataset_ids,
- query=query,
- retrieval=knowledge_set.retrieval,
- metadata_filtering=knowledge_set.metadata_filtering,
- )
- except DifyKnowledgeBaseClientError as exc:
- if exc.retryable:
- logger.warning(
- "eager knowledge retrieval temporarily unavailable",
- extra={
- "tenant_id": caller["tenant_id"],
- "app_id": caller["app_id"],
- "invoke_from": caller["invoke_from"],
- "knowledge_set_id": knowledge_set.id,
- "error_code": exc.error_code,
- "status_code": exc.status_code,
- "error_message": str(exc),
- },
- exc_info=True,
- )
- eager_results.append(
- DifyKnowledgeEagerResult(
- set_id=knowledge_set.id,
- set_name=knowledge_set.name,
- query=query,
- observation=TEMPORARY_UNAVAILABLE_OBSERVATION,
- status="temporarily_unavailable",
- )
- )
- continue
- logger.error(
- "eager knowledge retrieval failed",
+ caller = _build_caller_context(self.execution_context)
+ client = DifyKnowledgeBaseClient(
+ base_url=self.inner_api_url,
+ api_key=self.inner_api_key,
+ http_client=self.deps.services.dify_api_http_client,
+ )
+ eager_results: list[DifyKnowledgeEagerResult] = []
+ for knowledge_set in user_query_sets:
+ query = (knowledge_set.query.value or "").strip()
+ try:
+ response = await client.retrieve(
+ tenant_id=caller["tenant_id"],
+ user_id=caller["user_id"],
+ app_id=caller["app_id"],
+ user_from=caller["user_from"],
+ invoke_from=caller["invoke_from"],
+ dataset_ids=knowledge_set.dataset_ids,
+ query=query,
+ retrieval=knowledge_set.retrieval,
+ metadata_filtering=knowledge_set.metadata_filtering,
+ )
+ except DifyKnowledgeBaseClientError as exc:
+ if exc.retryable:
+ logger.warning(
+ "eager knowledge retrieval temporarily unavailable",
extra={
"tenant_id": caller["tenant_id"],
"app_id": caller["app_id"],
@@ -270,20 +273,44 @@ class DifyKnowledgeBaseLayer(
},
exc_info=True,
)
- raise
-
- eager_results.append(
- DifyKnowledgeEagerResult(
- set_id=knowledge_set.id,
- set_name=knowledge_set.name,
- query=query,
- observation=_format_observation(response, self.config, include_heading=False),
- status="success" if response.results else "empty",
+ eager_results.append(
+ DifyKnowledgeEagerResult(
+ set_id=knowledge_set.id,
+ set_name=knowledge_set.name,
+ query=query,
+ observation=TEMPORARY_UNAVAILABLE_OBSERVATION,
+ status="temporarily_unavailable",
+ )
)
+ continue
+ logger.error(
+ "eager knowledge retrieval failed",
+ extra={
+ "tenant_id": caller["tenant_id"],
+ "app_id": caller["app_id"],
+ "invoke_from": caller["invoke_from"],
+ "knowledge_set_id": knowledge_set.id,
+ "error_code": exc.error_code,
+ "status_code": exc.status_code,
+ "error_message": str(exc),
+ },
+ exc_info=True,
+ )
+ raise
+
+ eager_results.append(
+ DifyKnowledgeEagerResult(
+ set_id=knowledge_set.id,
+ set_name=knowledge_set.name,
+ query=query,
+ observation=_format_observation(response, self.config, include_heading=False),
+ status="success" if response.results else "empty",
)
+ )
- self.runtime_state.eager_results = eager_results
- self.runtime_state.eager_config_fingerprint = fingerprint
+ self.deps.layers[self.name]["state"] = State(
+ eager_results=eager_results, eager_config_fingerprint=fingerprint
+ ).model_dump(mode="json")
async def _retrieve_for_set(
self,
@@ -478,8 +505,9 @@ def _truncate_text(text: str, max_chars: int) -> str:
__all__ = [
"BLANK_QUERY_OBSERVATION",
- "DifyKnowledgeBaseDeps",
- "DifyKnowledgeBaseLayer",
+ "Config",
+ "State",
+ "Capability",
"NO_RESULTS_OBSERVATION",
"TEMPORARY_UNAVAILABLE_OBSERVATION",
]
diff --git a/dify-agent/src/dify_agent/layers/output/__init__.py b/dify-agent/src/dify_agent/layers/output/__init__.py
index 076fd00b1aa..9a3404ff6ad 100644
--- a/dify-agent/src/dify_agent/layers/output/__init__.py
+++ b/dify-agent/src/dify_agent/layers/output/__init__.py
@@ -5,6 +5,6 @@ server-side execution dependencies. Keep this package root import-safe for
client code that only needs to build run requests.
"""
-from dify_agent.layers.output.configs import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
+from dify_agent.layers.output.configs import DifyOutputLayerConfig
-__all__ = ["DIFY_OUTPUT_LAYER_TYPE_ID", "DifyOutputLayerConfig"]
+__all__ = ["DifyOutputLayerConfig"]
diff --git a/dify-agent/src/dify_agent/layers/output/configs.py b/dify-agent/src/dify_agent/layers/output/configs.py
index 0d73ef5411f..f3b1baaf2d8 100644
--- a/dify-agent/src/dify_agent/layers/output/configs.py
+++ b/dify-agent/src/dify_agent/layers/output/configs.py
@@ -8,17 +8,12 @@ imports do not pull in server execution code.
from __future__ import annotations
-from typing import ClassVar, Final
+from typing import ClassVar
-from pydantic import ConfigDict, JsonValue, field_validator
+from pydantic import BaseModel, ConfigDict, JsonValue, field_validator
-from agenton.layers import LayerConfig
-
-DIFY_OUTPUT_LAYER_TYPE_ID: Final[str] = "dify.output"
-
-
-class DifyOutputLayerConfig(LayerConfig):
+class DifyOutputLayerConfig(BaseModel):
"""Public config for the conventionally named structured output layer.
The runtime only reads the layer named by
@@ -48,4 +43,4 @@ class DifyOutputLayerConfig(LayerConfig):
return value
-__all__ = ["DIFY_OUTPUT_LAYER_TYPE_ID", "DifyOutputLayerConfig"]
+__all__ = ["DifyOutputLayerConfig"]
diff --git a/dify-agent/src/dify_agent/layers/output/output_layer.py b/dify-agent/src/dify_agent/layers/output/output_layer.py
index 206f0cceb25..8e4cfb3ae38 100644
--- a/dify-agent/src/dify_agent/layers/output/output_layer.py
+++ b/dify-agent/src/dify_agent/layers/output/output_layer.py
@@ -1,15 +1,7 @@
-"""Runtime layer for Dify Agent structured final output contracts.
-
-``DifyOutputLayer`` is intentionally state-free and does not participate in
-prompt, user prompt, or tool aggregation. Instead, the scheduler and runner read
-the conventionally named layer after ``Compositor.enter(...)`` and convert its
-top-level object JSON Schema into a ``ToolOutput(...)`` whose inner dynamic type
-both exposes the model-facing schema and validates runtime output. ``jsonschema``
-performs the real content validation inside that custom Pydantic-compatible
-dict-like type, so Pydantic AI's normal output validation flow can request
-retries without a separate Dify-owned output-validator callback. Keeping both
-steps here lets request validation and execution reuse the same schema checks
-without teaching Agenton core about output aggregation.
+"""Native structured output assembly with shared JSON Schema validation.
+
+The runner resolves output_type before invoking Pydantic AI. Its dynamic type
+exposes the schema and validates the result in Pydantic AI's retry pipeline.
"""
from __future__ import annotations
@@ -27,11 +19,13 @@ from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler, JsonValue
from pydantic.json_schema import JsonSchemaValue
from pydantic_ai.output import OutputSpec, ToolOutput
from pydantic_core import PydanticCustomError, core_schema
-from typing_extensions import Self, assert_never, override
+from typing_extensions import assert_never
-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PlainLayer
-from dify_agent.layers.output.configs import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai.capabilities import AbstractCapability
+from dify_agent.runtime.context import Deps
+from dify_agent.layers.output.configs import DifyOutputLayerConfig
_FINAL_OUTPUT_TOOL_NAME: Final[str] = "final_output"
@@ -52,21 +46,22 @@ class DifyOutputContract:
output_type: OutputSpec[object]
-@dataclass(slots=True)
-class DifyOutputLayer(PlainLayer[NoLayerDeps, DifyOutputLayerConfig, EmptyRuntimeState]):
- """State-free layer that stores the final structured output contract."""
+class Config(DifyOutputLayerConfig):
+ pass
- type_id = DIFY_OUTPUT_LAYER_TYPE_ID
- config: DifyOutputLayerConfig
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
- @classmethod
- @override
- def from_config(cls, config: DifyOutputLayerConfig) -> Self:
- """Create the output layer from validated public config."""
- return cls(config=DifyOutputLayerConfig.model_validate(config))
- def build_output_contract(self) -> DifyOutputContract:
+class Capability(AbstractCapability[Deps]):
+ """Explicit runner assembly for the native output_type parameter."""
+
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
+
+ def build_output_contract(self, deps: Deps) -> DifyOutputContract:
"""Return the pydantic-ai output contract for this layer.
The returned contract always keeps model-facing schema exposure plus
@@ -82,11 +77,12 @@ class DifyOutputLayer(PlainLayer[NoLayerDeps, DifyOutputLayerConfig, EmptyRuntim
references, or cannot be represented as a supported structured
output tool schema.
"""
- user_schema = deepcopy(self.config.json_schema)
+ config = Config.model_validate(deps.layers[self.name]["config"])
+ user_schema = deepcopy(config.json_schema)
_reject_non_local_refs(user_schema)
validated_output_type = _build_validated_output_type(
user_schema,
- description=self.config.description,
+ description=config.description,
)
return DifyOutputContract(
@@ -95,7 +91,7 @@ class DifyOutputLayer(PlainLayer[NoLayerDeps, DifyOutputLayerConfig, EmptyRuntim
ToolOutput(
validated_output_type,
name=_FINAL_OUTPUT_TOOL_NAME,
- strict=self.config.strict,
+ strict=config.strict,
),
),
)
@@ -310,4 +306,4 @@ def _sort_error_path(path: Sequence[object]) -> tuple[str, ...]:
return tuple(str(segment) for segment in path)
-__all__ = ["DifyOutputContract", "DifyOutputLayer"]
+__all__ = ["DifyOutputContract", "Config", "State", "Capability"]
diff --git a/dify-agent/src/dify_agent/layers/prompt/__init__.py b/dify-agent/src/dify_agent/layers/prompt/__init__.py
new file mode 100644
index 00000000000..2ec75f0f7dd
--- /dev/null
+++ b/dify-agent/src/dify_agent/layers/prompt/__init__.py
@@ -0,0 +1,5 @@
+"""Client-safe prompt configuration exports."""
+
+from .configs import Config
+
+__all__ = ["Config"]
diff --git a/dify-agent/src/dify_agent/layers/prompt/configs.py b/dify-agent/src/dify_agent/layers/prompt/configs.py
new file mode 100644
index 00000000000..c589c730dc2
--- /dev/null
+++ b/dify-agent/src/dify_agent/layers/prompt/configs.py
@@ -0,0 +1,10 @@
+"""Client-safe JSON configuration for the prompt module."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Config(BaseModel):
+ prefix: list[str] | str = Field(default_factory=list)
+ user: list[str] | str = Field(default_factory=list)
+ suffix: list[str] | str = Field(default_factory=list)
+ model_config = ConfigDict(extra="forbid")
diff --git a/dify-agent/src/dify_agent/layers/prompt/layer.py b/dify-agent/src/dify_agent/layers/prompt/layer.py
new file mode 100644
index 00000000000..7b76e16e09c
--- /dev/null
+++ b/dify-agent/src/dify_agent/layers/prompt/layer.py
@@ -0,0 +1,31 @@
+"""Serializable prompt module; instruction ordering is deliberately unspecified."""
+
+from pydantic import BaseModel, ConfigDict
+
+from dify_agent.layers.prompt.configs import Config
+from pydantic_ai import RunContext
+from pydantic_ai.messages import UserContent
+from pydantic_ai.toolsets import FunctionToolset
+
+from dify_agent.runtime.context import Deps
+
+
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+
+
+class Toolset(FunctionToolset[Deps]):
+ def __init__(self, name: str):
+ self.name = name
+ super().__init__(id=name, instructions=self._render_instructions)
+
+ def _render_instructions(self, ctx: RunContext[Deps]) -> str:
+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])
+ return "\n\n".join([*_fragments(config.prefix), *_fragments(config.suffix)])
+
+ def build_user_content(self, deps: Deps) -> list[UserContent]:
+ return list(_fragments(Config.model_validate(deps.layers[self.name]["config"]).user))
+
+
+def _fragments(value: list[str] | str) -> list[str]:
+ return [value] if isinstance(value, str) else value
diff --git a/dify-agent/src/dify_agent/layers/runtime/__init__.py b/dify-agent/src/dify_agent/layers/runtime/__init__.py
index 872ed9120c4..8761ed8a621 100644
--- a/dify-agent/src/dify_agent/layers/runtime/__init__.py
+++ b/dify-agent/src/dify_agent/layers/runtime/__init__.py
@@ -1,4 +1,3 @@
-from .configs import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
-from .layer import DifyRuntimeLayer
+from .configs import DifyRuntimeLayerConfig
-__all__ = ["DIFY_RUNTIME_LAYER_TYPE_ID", "DifyRuntimeLayer", "DifyRuntimeLayerConfig"]
+__all__ = ["DifyRuntimeLayerConfig"]
diff --git a/dify-agent/src/dify_agent/layers/runtime/configs.py b/dify-agent/src/dify_agent/layers/runtime/configs.py
index f7f3a576dbb..5761a486b8d 100644
--- a/dify-agent/src/dify_agent/layers/runtime/configs.py
+++ b/dify-agent/src/dify_agent/layers/runtime/configs.py
@@ -1,17 +1,14 @@
"""Client-safe config for operation-scoped RuntimeLease acquisition."""
-from typing import ClassVar, Final
+from typing import ClassVar
-from agenton.layers import LayerConfig
-from pydantic import ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field
-DIFY_RUNTIME_LAYER_TYPE_ID: Final[str] = "dify.runtime"
-
-class DifyRuntimeLayerConfig(LayerConfig):
+class DifyRuntimeLayerConfig(BaseModel):
backend_binding_ref: str = Field(min_length=1)
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-__all__ = ["DIFY_RUNTIME_LAYER_TYPE_ID", "DifyRuntimeLayerConfig"]
+__all__ = ["DifyRuntimeLayerConfig"]
diff --git a/dify-agent/src/dify_agent/layers/runtime/layer.py b/dify-agent/src/dify_agent/layers/runtime/layer.py
index e6fbaf70aff..b2889f07b72 100644
--- a/dify-agent/src/dify_agent/layers/runtime/layer.py
+++ b/dify-agent/src/dify_agent/layers/runtime/layer.py
@@ -1,75 +1,40 @@
-"""Agenton layer exposing one operation-scoped RuntimeLease."""
+"""Acquire an operation lease without owning Binding or Workspace retirement."""
-from collections.abc import AsyncGenerator
-from contextlib import asynccontextmanager
-from dataclasses import dataclass, field
-from typing import ClassVar
+from typing import override
-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PlainLayer
-from typing_extensions import Self, override
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai import RunContext
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.capabilities.abstract import WrapRunHandler
+from pydantic_ai.run import AgentRunResult
-from dify_agent.layers.runtime.configs import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
-from dify_agent.runtime_backend import ExecutionBindingBackend, RuntimeLease
+from dify_agent.layers.runtime.configs import DifyRuntimeLayerConfig
+from dify_agent.runtime.context import Deps
from dify_agent.runtime_backend.leases import open_runtime_lease
-@dataclass(slots=True)
-class DifyRuntimeLayer(PlainLayer[NoLayerDeps, DifyRuntimeLayerConfig, EmptyRuntimeState]):
- """Acquire/release a Binding without owning its product lifecycle."""
+class Config(DifyRuntimeLayerConfig):
+ pass
- type_id: ClassVar[str | None] = DIFY_RUNTIME_LAYER_TYPE_ID
- config: DifyRuntimeLayerConfig
- backend: ExecutionBindingBackend
- _lease: RuntimeLease | None = field(default=None, init=False)
- @classmethod
- @override
- def from_config(cls, config: DifyRuntimeLayerConfig) -> Self:
- del config
- raise TypeError("DifyRuntimeLayer requires a server-injected ExecutionBindingBackend")
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
- @classmethod
- def from_config_with_backend(
- cls,
- config: DifyRuntimeLayerConfig,
- *,
- backend: ExecutionBindingBackend,
- ) -> Self:
- return cls(config=DifyRuntimeLayerConfig.model_validate(config), backend=backend)
- @property
- def lease(self) -> RuntimeLease:
- if self._lease is None:
- raise RuntimeError("DifyRuntimeLayer lease is only available inside resource_context()")
- return self._lease
+class Capability(AbstractCapability[Deps]):
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
@override
- @asynccontextmanager
- async def resource_context(self) -> AsyncGenerator[None]:
- if self._lease is not None:
- raise RuntimeError("DifyRuntimeLayer resource_context() is already active")
- async with open_runtime_lease(self.backend, self.config.backend_binding_ref) as lease:
- self._lease = lease
+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:
+ config = Config.model_validate(ctx.deps.layers[self.name]["config"])
+ profile = ctx.deps.services.runtime_backend_profile
+ if profile is None:
+ raise ValueError("Runtime module requires a configured runtime backend.")
+ async with open_runtime_lease(profile.execution_bindings, config.backend_binding_ref) as lease:
+ ctx.deps.resources.leases[self.name] = lease
try:
- yield
+ return await handler()
finally:
- self._lease = None
-
- @override
- async def on_context_create(self) -> None:
- _ = self.lease
-
- @override
- async def on_context_resume(self) -> None:
- _ = self.lease
-
- @override
- async def on_context_suspend(self) -> None:
- _ = self.lease
-
- @override
- async def on_context_delete(self) -> None:
- _ = self.lease
-
-
-__all__ = ["DifyRuntimeLayer"]
+ del ctx.deps.resources.leases[self.name]
diff --git a/dify-agent/src/dify_agent/layers/shell/__init__.py b/dify-agent/src/dify_agent/layers/shell/__init__.py
index 34800d69471..5a6466e0f1f 100644
--- a/dify-agent/src/dify_agent/layers/shell/__init__.py
+++ b/dify-agent/src/dify_agent/layers/shell/__init__.py
@@ -6,7 +6,6 @@ client code that only needs to build run requests.
"""
from dify_agent.layers.shell.configs import (
- DIFY_SHELL_LAYER_TYPE_ID,
DifyShellCliToolConfig,
DifyShellEnvVarConfig,
DifyShellLayerConfig,
@@ -14,7 +13,6 @@ from dify_agent.layers.shell.configs import (
)
__all__ = [
- "DIFY_SHELL_LAYER_TYPE_ID",
"DifyShellCliToolConfig",
"DifyShellEnvVarConfig",
"DifyShellLayerConfig",
diff --git a/dify-agent/src/dify_agent/layers/shell/configs.py b/dify-agent/src/dify_agent/layers/shell/configs.py
index 77d7d05a3f7..e552405f1ef 100644
--- a/dify-agent/src/dify_agent/layers/shell/configs.py
+++ b/dify-agent/src/dify_agent/layers/shell/configs.py
@@ -1,21 +1,18 @@
-"""Client-safe DTOs for the Dify shell Agenton layer.
+"""Client-safe DTOs for the Dify shell layer.
Server-only Agent Stub and redaction settings are injected by the runtime
-provider factory. The Sandbox dependency supplies the active shellctl data
+runtime services. The Sandbox dependency supplies the active shellctl data
plane. Public config carries product-level Agent Soul settings that affect the
workspace itself: CLI tool bootstrap commands, normal environment variables,
secret environment variable names. Sandbox selection is a deployment concern.
"""
import re
-from typing import ClassVar, Final
+from typing import ClassVar
from pydantic import BaseModel, ConfigDict, Field, field_validator
-from agenton.layers import LayerConfig
-
-DIFY_SHELL_LAYER_TYPE_ID: Final[str] = "dify.shell"
_ENV_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
@@ -67,9 +64,12 @@ class DifyShellCliToolConfig(BaseModel):
return [command for command in (item.strip() for item in value) if command]
-class DifyShellLayerConfig(LayerConfig):
+class DifyShellLayerConfig(BaseModel):
"""Public product behavior for the Sandbox-backed Dify Shell layer."""
+ runtime: str = "runtime"
+ execution_context: str | None = "execution_context"
+
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
cli_tools: list[DifyShellCliToolConfig] = Field(default_factory=list)
@@ -79,7 +79,6 @@ class DifyShellLayerConfig(LayerConfig):
__all__ = [
- "DIFY_SHELL_LAYER_TYPE_ID",
"DifyShellCliToolConfig",
"DifyShellEnvVarConfig",
"DifyShellLayerConfig",
diff --git a/dify-agent/src/dify_agent/layers/shell/layer.py b/dify-agent/src/dify_agent/layers/shell/layer.py
index 354818d91f2..b923c3147c5 100644
--- a/dify-agent/src/dify_agent/layers/shell/layer.py
+++ b/dify-agent/src/dify_agent/layers/shell/layer.py
@@ -7,21 +7,16 @@ import json
import logging
import re
from dataclasses import dataclass, field
-from typing import ClassVar, NotRequired, Protocol, TypedDict, runtime_checkable
+from typing import ClassVar, NotRequired, Protocol, TypedDict, override, runtime_checkable
from pydantic import BaseModel, ConfigDict, Field, NonNegativeInt, field_validator, model_validator
-from pydantic_ai import Tool
-from typing_extensions import Self, override
-
-from agenton.layers import (
- EmptyRuntimeState,
- LayerDeps,
- NoLayerDeps,
- PlainLayer,
- PydanticAILayer,
- PydanticAIPrompt,
- PydanticAITool,
-)
+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 pydantic_ai.toolsets import FunctionToolset
+from typing_extensions import Self
+
from dify_agent.adapters.shell.protocols import (
CompleteShellCommandResult,
ShellCommandProtocol,
@@ -29,10 +24,11 @@ from dify_agent.adapters.shell.protocols import (
ShellPromptObservation,
)
from dify_agent.agent_stub.protocol import AGENT_STUB_AUTH_JWE_ENV_VAR
-from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory, build_shell_agent_stub_env
+from dify_agent.agent_stub.shell_env import build_shell_agent_stub_env
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.runtime.layer import DifyRuntimeLayer
-from dify_agent.layers.shell.configs import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
+from dify_agent.layers.runtime.layer import Capability as RuntimeCapability
+from dify_agent.runtime.context import Deps
+from dify_agent.layers.shell.configs import DifyShellLayerConfig
from dify_agent.layers.shell.output_text import normalized_output_text, utf8_prefix, utf8_suffix
from dify_agent.runtime.command_runner import execute_complete_with_commands
from dify_agent.runtime_backend import RuntimeLease
@@ -173,12 +169,12 @@ type ShellRunToolResult = str | ShellToolErrorObservation
type ShellInterruptToolResult = str | ShellToolErrorObservation
-class DifyShellLayerDeps(LayerDeps):
- execution_context: PlainLayer[NoLayerDeps, DifyExecutionContextLayerConfig, EmptyRuntimeState] | None # pyright: ignore[reportUninitializedInstanceVariable]
- runtime: DifyRuntimeLayer # pyright: ignore[reportUninitializedInstanceVariable]
+class Config(DifyShellLayerConfig):
+ pass
-class DifyShellRuntimeState(BaseModel):
+class State(BaseModel):
+ initialized: bool = False
job_ids: list[str] = Field(default_factory=list)
job_offsets: dict[str, NonNegativeInt] = Field(default_factory=dict)
@@ -203,102 +199,118 @@ class DifyShellRuntimeState(BaseModel):
CompleteRemoteCommandResult = CompleteShellCommandResult
-@dataclass(slots=True)
-class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerConfig, DifyShellRuntimeState]):
- """Expose Shell tools over the active RuntimeLease without owning it.
-
- Create optionally bootstraps configured CLI tools in the lease's Workspace.
- Suspend and delete best-effort remove tracked shellctl jobs, then clear job
- ids and offsets so they do not persist across requests. Commands, files,
- Home, and cwd come only from ``DifyRuntimeLayer.lease``. Persistent Binding
- and Workspace lifecycle remains exclusively owned by Dify API.
- """
+class Capability(AbstractCapability[Deps]):
+ """Own one ShellSession, bootstrap once and clean jobs on every outcome."""
- type_id: ClassVar[str | None] = DIFY_SHELL_LAYER_TYPE_ID
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
- config: DifyShellLayerConfig
- shell_redact_patterns: list[str] = field(default_factory=list)
- agent_stub_api_base_url: str | None = None
- agent_stub_token_factory: ShellAgentStubTokenFactory | None = None
- _job_agent_stub_tokens: dict[str, str] = field(default_factory=dict, init=False, repr=False)
+ @override
+ def get_ordering(self) -> CapabilityOrdering:
+ return CapabilityOrdering(wrapped_by=[RuntimeCapability], requires=[RuntimeCapability])
- @classmethod
@override
- def from_config(cls, config: DifyShellLayerConfig) -> Self:
- del config
- raise TypeError("DifyShellLayer requires server-injected settings and must use a provider factory.")
+ def get_instructions(self):
+ return self._instructions
- @classmethod
- def from_config_with_settings(
- cls,
- config: DifyShellLayerConfig,
- *,
- shell_redact_patterns: list[str] | None = None,
- agent_stub_api_base_url: str | None = None,
- agent_stub_token_factory: ShellAgentStubTokenFactory | None = None,
- ) -> Self:
- return cls(
- config=config,
- shell_redact_patterns=shell_redact_patterns or [],
- agent_stub_api_base_url=agent_stub_api_base_url,
- agent_stub_token_factory=agent_stub_token_factory,
- )
+ def _instructions(self, ctx: RunContext[Deps]) -> str:
+ session = ctx.deps.resources.shells[self.name]
+ return f"{session.build_prefix_prompt()}\n\n{_SHELL_LAYER_SUFFIX_PROMPT}"
- @property
@override
- def prefix_prompts(self) -> Sequence[PydanticAIPrompt[object]]:
- return [self._build_prefix_prompt]
+ def get_toolset(self) -> FunctionToolset[Deps]:
+ toolset = FunctionToolset[Deps](id=self.name, sequential=True)
+
+ @toolset.tool(name="shell_run")
+ async def shell_run(
+ ctx: RunContext[Deps], script: str, timeout: float = DEFAULT_TIMEOUT_SECONDS
+ ) -> ShellRunToolResult:
+ """Start a shell job and return its output and status."""
+ return await ctx.deps.resources.shells[self.name]._tool_run(script, timeout)
+
+ @toolset.tool(name="shell_wait")
+ async def shell_wait(
+ ctx: RunContext[Deps], job_id: str, timeout: float = DEFAULT_TIMEOUT_SECONDS
+ ) -> ShellRunToolResult:
+ """Wait for output or completion from an existing shell job."""
+ return await ctx.deps.resources.shells[self.name]._tool_wait(job_id, timeout)
+
+ @toolset.tool(name="shell_input")
+ async def shell_input(
+ ctx: RunContext[Deps], job_id: str, text: str, timeout: float = DEFAULT_TIMEOUT_SECONDS
+ ) -> ShellRunToolResult:
+ """Send stdin to a shell job and wait for its next output."""
+ return await ctx.deps.resources.shells[self.name]._tool_input(job_id, text, timeout)
+
+ @toolset.tool(name="shell_interrupt")
+ async def shell_interrupt(
+ ctx: RunContext[Deps], job_id: str, grace_seconds: float = DEFAULT_TERMINATE_GRACE_SECONDS
+ ) -> ShellInterruptToolResult:
+ """Interrupt a running shell job and return its final status."""
+ return await ctx.deps.resources.shells[self.name]._tool_interrupt(job_id, grace_seconds)
+
+ return toolset
- @property
@override
- def suffix_prompts(self) -> Sequence[PydanticAIPrompt[object]]:
- return [_shell_layer_suffix_prompt]
+ async def wrap_run(self, ctx: RunContext[Deps], *, handler: WrapRunHandler) -> AgentRunResult:
+ session = ShellSession(self.name, ctx.deps)
+ ctx.deps.resources.shells[self.name] = session
+ try:
+ state = session.runtime_state
+ if not state.initialized:
+ script = _workspace_bootstrap_script(session.config)
+ if script:
+ result = await session._run_internal_script_complete(script, cwd=session._require_workspace_cwd())
+ if result.exit_code != 0 or not result.output_complete:
+ raise RuntimeError(
+ f"Failed to bootstrap shell workspace: {result.status} exit_code={result.exit_code}"
+ )
+ state.initialized = True
+ session.save_state(state)
+ return await handler()
+ finally:
+ try:
+ await session._delete_tracked_jobs_best_effort(session.runtime_state.job_ids)
+ finally:
+ session._clear_tracked_jobs()
+ del ctx.deps.resources.shells[self.name]
- @property
- @override
- def tools(self) -> Sequence[PydanticAITool[object]]:
- return [
- Tool(self._tool_run, name="shell_run"),
- Tool(self._tool_wait, name="shell_wait"),
- Tool(self._tool_input, name="shell_input"),
- Tool(self._tool_interrupt, name="shell_interrupt"),
- ]
-
- def _build_prefix_prompt(self) -> str:
- execution_context = self.deps.execution_context
- is_build_draft = (
- execution_context is not None and execution_context.config.agent_config_version_kind == "build_draft"
- )
- working_location_prompt = (
- _BUILD_DRAFT_WORKING_LOCATION_PROMPT if is_build_draft else _DEFAULT_WORKING_LOCATION_PROMPT
- )
- return f"{_SHELL_LAYER_PREFIX_PROMPT}\n\n{working_location_prompt}"
- @override
- async def on_context_create(self) -> None:
- bootstrap_script = _workspace_bootstrap_script(self.config)
- if not bootstrap_script:
- return
- result = await self._run_internal_script_complete(bootstrap_script, cwd=self._require_workspace_cwd())
- if result.exit_code != 0 or not result.output_complete:
- raise RuntimeError(
- f"Failed to bootstrap shell workspace {self._require_workspace_cwd()}: "
- f"{result.status} exit_code={result.exit_code}"
- )
+@dataclass(slots=True)
+class ShellSession:
+ """Run-scoped shell operations over borrowed lease and canonical JSON state.
- @override
- async def on_context_resume(self) -> None:
- _ = self._require_resource()
+ Capabilities and tools share this live command adapter, never copied Config
+ or State models. Shell tools run sequentially because offsets and tokens
+ share one session. Binding and Workspace retirement remain API-owned.
+ """
- @override
- async def on_context_suspend(self) -> None:
- await self._delete_tracked_jobs_best_effort(self.runtime_state.job_ids)
- self._clear_tracked_jobs()
+ name: str
+ deps: Deps
+ _job_agent_stub_tokens: dict[str, str] = field(default_factory=dict, init=False, repr=False)
- @override
- async def on_context_delete(self) -> None:
- await self._delete_tracked_jobs_best_effort(self.runtime_state.job_ids)
- self._clear_tracked_jobs()
+ @property
+ def config(self) -> Config:
+ return Config.model_validate(self.deps.layers[self.name]["config"])
+
+ @property
+ def runtime_state(self) -> State:
+ return State.model_validate(self.deps.layers[self.name]["state"])
+
+ def save_state(self, state: State) -> None:
+ self.deps.layers[self.name]["state"] = state.model_dump(mode="json")
+
+ def build_prefix_prompt(self) -> str:
+ context_name = self.config.execution_context
+ context = (
+ DifyExecutionContextLayerConfig.model_validate(self.deps.layers[context_name]["config"])
+ if context_name
+ else None
+ )
+ is_build_draft = context is not None and context.agent_config_version_kind == "build_draft"
+ working = _BUILD_DRAFT_WORKING_LOCATION_PROMPT if is_build_draft else _DEFAULT_WORKING_LOCATION_PROMPT
+ return f"{_SHELL_LAYER_PREFIX_PROMPT}\n\n{working}"
async def _tool_run(self, script: str, timeout: float = DEFAULT_TIMEOUT_SECONDS) -> ShellRunToolResult:
"""Start a shell job in the current workspace and return its output and status."""
@@ -312,12 +324,17 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
env=env,
timeout=timeout,
)
+ # Register the remote job before observing output so cancellation during
+ # a tail request still leaves cleanup with its job and redaction token.
+ self._remember_job_id(result.job_id)
+ self._remember_job_offset(result.job_id, 0)
+ if agent_stub_token is not None and not result.done:
+ self._job_agent_stub_tokens[result.job_id] = agent_stub_token
observation = await render_prompt_observation_from_result(
self._require_resource().commands,
result,
edge_bytes=_SHELL_OUTPUT_PROMPT_EDGE_BYTES,
)
- self._remember_job_id(result.job_id)
self._remember_job_offset(result.job_id, observation.offset)
if agent_stub_token is not None and not result.done:
self._job_agent_stub_tokens[result.job_id] = agent_stub_token
@@ -502,7 +519,10 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
)
def _require_resource(self) -> RuntimeLease:
- return self.deps.runtime.lease
+ lease = self.deps.resources.leases.get(self.config.runtime)
+ if lease is None:
+ raise RuntimeError("Shell requires an active Runtime lease.")
+ return lease
def _require_workspace_cwd(self) -> str:
return self._require_resource().layout.workspace_dir
@@ -518,12 +538,14 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
def _remember_job_id(self, job_id: str) -> None:
if job_id in self.runtime_state.job_ids:
return
- self.runtime_state.job_ids = [*self.runtime_state.job_ids, job_id]
+ state = self.runtime_state
+ state.job_ids = [*state.job_ids, job_id]
+ self.save_state(state)
def _remember_job_offset(self, job_id: str, offset: int) -> None:
- job_offsets = dict(self.runtime_state.job_offsets)
- job_offsets[job_id] = offset
- self.runtime_state.job_offsets = job_offsets
+ state = self.runtime_state
+ state.job_offsets = {**state.job_offsets, job_id: offset}
+ self.save_state(state)
async def _delete_tracked_jobs_best_effort(self, job_ids: Sequence[str]) -> None:
commands = self._require_resource().commands
@@ -538,8 +560,10 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
)
def _clear_tracked_jobs(self) -> None:
- self.runtime_state.job_offsets = {}
- self.runtime_state.job_ids = []
+ state = self.runtime_state
+ state.job_offsets = {}
+ state.job_ids = []
+ self.save_state(state)
self._job_agent_stub_tokens.clear()
def _build_shell_command_env(
@@ -552,12 +576,16 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
env["HOME"] = self._require_resource().layout.home_dir
if not include_agent_stub_env:
return env
- execution_context_layer = self.deps.execution_context
- execution_context = execution_context_layer.config if execution_context_layer is not None else None
+ context_name = self.config.execution_context
+ execution_context = (
+ DifyExecutionContextLayerConfig.model_validate(self.deps.layers[context_name]["config"])
+ if context_name
+ else None
+ )
agent_stub_env = build_shell_agent_stub_env(
- agent_stub_api_base_url=self.agent_stub_api_base_url,
+ agent_stub_api_base_url=self.deps.services.agent_stub_api_base_url,
execution_context=execution_context,
- token_factory=self.agent_stub_token_factory,
+ token_factory=self.deps.services.agent_stub_token_factory,
session_id=None,
)
if agent_stub_env is None:
@@ -587,7 +615,7 @@ class DifyShellLayer(PydanticAILayer[DifyShellLayerDeps, object, DifyShellLayerC
if value and len(value) > 8:
text = text.replace(value, "***")
# Server-level + per-agent regex patterns.
- for pattern in (*self.shell_redact_patterns, *self.config.redact_patterns):
+ for pattern in (*self.deps.services.shell_redact_patterns, *self.config.redact_patterns):
text = re.sub(pattern, "***", text)
return text
@@ -623,10 +651,6 @@ async def render_prompt_observation_from_result(
return ShellPromptObservation(text=text, output_path=output_path, offset=offset)
-def _shell_layer_suffix_prompt() -> str:
- return _SHELL_LAYER_SUFFIX_PROMPT
-
-
def _metadata_dict(
*,
job_id: str,
@@ -738,10 +762,11 @@ def _tagged_shell_observation(metadata: dict[str, object], output: str) -> str:
__all__ = [
+ "Config",
+ "State",
+ "Capability",
+ "ShellSession",
"CompleteRemoteCommandResult",
- "DifyShellLayer",
- "DifyShellLayerDeps",
- "DifyShellRuntimeState",
"DEFAULT_TERMINATE_GRACE_SECONDS",
"DEFAULT_TIMEOUT_SECONDS",
"render_prompt_observation_from_result",
diff --git a/dify-agent/src/dify_agent/layers/user_prompt/__init__.py b/dify-agent/src/dify_agent/layers/user_prompt/__init__.py
index f675b1c0140..142c770ab52 100644
--- a/dify-agent/src/dify_agent/layers/user_prompt/__init__.py
+++ b/dify-agent/src/dify_agent/layers/user_prompt/__init__.py
@@ -1,7 +1,6 @@
"""Client-safe exports for the Agent App multimodal user prompt layer."""
from dify_agent.layers.user_prompt.configs import (
- DIFY_USER_PROMPT_LAYER_TYPE_ID,
DifyUserPromptDownloadConfig,
DifyUserPromptFileConfig,
DifyUserPromptFileType,
@@ -10,7 +9,6 @@ from dify_agent.layers.user_prompt.configs import (
)
__all__ = [
- "DIFY_USER_PROMPT_LAYER_TYPE_ID",
"DifyUserPromptDownloadConfig",
"DifyUserPromptFileConfig",
"DifyUserPromptFileType",
diff --git a/dify-agent/src/dify_agent/layers/user_prompt/configs.py b/dify-agent/src/dify_agent/layers/user_prompt/configs.py
index fc9fa273e7d..f0f50ee6158 100644
--- a/dify-agent/src/dify_agent/layers/user_prompt/configs.py
+++ b/dify-agent/src/dify_agent/layers/user_prompt/configs.py
@@ -4,18 +4,15 @@ from __future__ import annotations
import base64
import binascii
-from typing import Annotated, ClassVar, Final, Literal, Self
+from typing import Annotated, ClassVar, Literal, Self
-from pydantic import ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
-from agenton.layers import LayerConfig
-
-DIFY_USER_PROMPT_LAYER_TYPE_ID: Final[str] = "dify.user_prompt"
type DifyUserPromptFileType = Literal["image", "document", "audio", "video", "custom"]
-class DifyUserPromptImageConfig(LayerConfig):
+class DifyUserPromptImageConfig(BaseModel):
"""One image delivered directly to the configured vision model.
Callers provide either an HTTP(S) URL or base64 bytes. Opaque Dify file
@@ -47,7 +44,7 @@ class DifyUserPromptImageConfig(LayerConfig):
return self
-class DifyUserPromptDownloadConfig(LayerConfig):
+class DifyUserPromptDownloadConfig(BaseModel):
delivery: Literal["download"] = "download"
type: DifyUserPromptFileType
transfer_method: Literal["remote_url", "local_file", "tool_file", "datasource_file"]
@@ -71,7 +68,7 @@ type DifyUserPromptFileConfig = Annotated[
]
-class DifyUserPromptLayerConfig(LayerConfig):
+class DifyUserPromptLayerConfig(BaseModel):
"""User text plus images that should be sent in the same model turn."""
text: str = Field(min_length=1)
@@ -81,7 +78,6 @@ class DifyUserPromptLayerConfig(LayerConfig):
__all__ = [
- "DIFY_USER_PROMPT_LAYER_TYPE_ID",
"DifyUserPromptDownloadConfig",
"DifyUserPromptFileConfig",
"DifyUserPromptFileType",
diff --git a/dify-agent/src/dify_agent/layers/user_prompt/layer.py b/dify-agent/src/dify_agent/layers/user_prompt/layer.py
index edcdf0a45bc..d677d82e651 100644
--- a/dify-agent/src/dify_agent/layers/user_prompt/layer.py
+++ b/dify-agent/src/dify_agent/layers/user_prompt/layer.py
@@ -4,39 +4,40 @@ from __future__ import annotations
import base64
import json
-from dataclasses import dataclass
-from typing import ClassVar, assert_never
+from typing import assert_never
from pydantic_ai.messages import BinaryContent, ImageUrl, UserContent
-from typing_extensions import Self, override
-from agenton.layers import EmptyRuntimeState, NoLayerDeps, PydanticAILayer
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai.capabilities import AbstractCapability
+from dify_agent.runtime.context import Deps
from dify_agent.layers.user_prompt.configs import (
- DIFY_USER_PROMPT_LAYER_TYPE_ID,
DifyUserPromptDownloadConfig,
DifyUserPromptImageConfig,
DifyUserPromptLayerConfig,
)
-@dataclass(slots=True)
-class DifyUserPromptLayer(PydanticAILayer[NoLayerDeps, object, DifyUserPromptLayerConfig, EmptyRuntimeState]):
- """State-free layer for a text prompt and directly attached images."""
+class Config(DifyUserPromptLayerConfig):
+ pass
- type_id: ClassVar[str | None] = DIFY_USER_PROMPT_LAYER_TYPE_ID
- config: DifyUserPromptLayerConfig
- @classmethod
- @override
- def from_config(cls, config: DifyUserPromptLayerConfig) -> Self:
- return cls(config=DifyUserPromptLayerConfig.model_validate(config))
+class State(BaseModel):
+ model_config = ConfigDict(extra="forbid")
- @property
- @override
- def user_prompts(self) -> list[UserContent]:
+
+class Capability(AbstractCapability[Deps]):
+ """Resolve current user content before calling Agent.run."""
+
+ def __init__(self, name: str):
+ self.id = name
+ self.name = name
+
+ def build_user_content(self, deps: Deps) -> list[UserContent]:
+ config = Config.model_validate(deps.layers[self.name]["config"])
images: list[UserContent] = []
downloads: list[DifyUserPromptDownloadConfig] = []
- for file in self.config.files:
+ for file in config.files:
match file.delivery:
case "multimodal":
images.append(_to_image_content(file))
@@ -44,7 +45,7 @@ class DifyUserPromptLayer(PydanticAILayer[NoLayerDeps, object, DifyUserPromptLay
downloads.append(file)
case _:
assert_never(file)
- return [_append_file_downloads(self.config.text, downloads), *images]
+ return [_append_file_downloads(config.text, downloads), *images]
def _append_file_downloads(text: str, files: list[DifyUserPromptDownloadConfig]) -> str:
@@ -88,4 +89,4 @@ def _identifier_from_filename(filename: str, file_format: str) -> str:
return filename
-__all__ = ["DifyUserPromptLayer"]
+__all__ = ["Config", "State", "Capability"]
diff --git a/dify-agent/src/dify_agent/protocol/__init__.py b/dify-agent/src/dify_agent/protocol/__init__.py
index 0eb18b57a36..11664536ce5 100644
--- a/dify-agent/src/dify_agent/protocol/__init__.py
+++ b/dify-agent/src/dify_agent/protocol/__init__.py
@@ -15,10 +15,7 @@ from .schemas import (
CancelRunResponse,
CreateRunRequest,
CreateRunResponse,
- DeferredToolCallPayload,
- DeferredToolResultsPayload,
EmptyRunEventData,
- LayerExitSignals,
PydanticAIStreamRunEvent,
RunCancelledEvent,
RunCancelledEventData,
@@ -30,12 +27,12 @@ from .schemas import (
RunFailedEventData,
RunFailureType,
RunLayerSpec,
+ SessionSnapshot,
RunStartedEvent,
RunStatus,
RunStatusResponse,
RunSucceededEvent,
RunSucceededEventData,
- normalize_composition,
utc_now,
)
from .execution_binding import (
@@ -76,14 +73,11 @@ __all__ = [
"CreateExecutionBindingResponse",
"CreateHomeSnapshotFromBindingRequest",
"DeleteHomeSnapshotRequest",
- "DeferredToolCallPayload",
- "DeferredToolResultsPayload",
"DIFY_AGENT_HISTORY_LAYER_ID",
"DIFY_AGENT_MODEL_LAYER_ID",
"DIFY_AGENT_OUTPUT_LAYER_ID",
"DestroyExecutionBindingRequest",
"EmptyRunEventData",
- "LayerExitSignals",
"HomeSnapshotResponse",
"PydanticAIStreamRunEvent",
"RUN_EVENT_ADAPTER",
@@ -97,11 +91,11 @@ __all__ = [
"RunFailedEventData",
"RunFailureType",
"RunLayerSpec",
+ "SessionSnapshot",
"RunStartedEvent",
"RunStatus",
"RunStatusResponse",
"RunSucceededEvent",
"RunSucceededEventData",
- "normalize_composition",
"utc_now",
]
diff --git a/dify-agent/src/dify_agent/protocol/schemas.py b/dify-agent/src/dify_agent/protocol/schemas.py
index e0cb62c7f00..0318649c632 100644
--- a/dify-agent/src/dify_agent/protocol/schemas.py
+++ b/dify-agent/src/dify_agent/protocol/schemas.py
@@ -1,36 +1,10 @@
-"""Public HTTP protocol schemas for the Dify Agent run API.
-
-This module is the shared wire contract for the FastAPI server, runtime event
-producers, storage adapters, and Python client. Create-run requests expose a
-Dify-friendly ``composition.layers[].config`` shape so callers can describe one
-layer in one place; the server normalizes that public DTO into Agenton's
-state-only ``CompositorConfig`` plus node-name keyed per-run configs before
-calling ``Compositor.enter(configs=...)``. Session snapshots, deferred tool
-results, and ``on_exit`` stay top-level because they are per-run resume state or
-exit policy, not graph node definition.
-
-The server still constructs layers only from explicit provider type ids, keeping
-HTTP input data-only and preventing unsafe import-path construction. Run events
-are append-only records; Redis stream ids (or in-memory equivalents in tests) are
-the public cursors used by polling and SSE replay. Event envelopes keep the
-public ``id``/``run_id``/``type``/``data``/``created_at`` shape, while each
-``type`` has a typed ``data`` model so OpenAPI, Redis replay, and clients parse
-the same payload contract. Model/provider selection is part of the submitted
-composition, not a top-level run field; the runtime reads the model layer named
-by ``DIFY_AGENT_MODEL_LAYER_ID``, the optional history layer named by
-``DIFY_AGENT_HISTORY_LAYER_ID``, and the optional structured output layer named
-by ``DIFY_AGENT_OUTPUT_LAYER_ID``. Request-level ``on_exit`` signals decide
-whether each active layer is suspended or deleted when the run exits, with
-suspend as the default so terminal events can include resumable snapshots.
-Successful runs always publish the resumable Agenton session snapshot on the
-terminal ``run_succeeded`` event; failed and cancelled runs publish it when the
-compositor context was entered and exited. Success includes either the final JSON-safe
-``output`` or a deferred external ``deferred_tool_call`` payload. Session
-snapshots carry only layer lifecycle/runtime state in
-compositor order; they do not persist output-layer config. Resumed
-structured-output runs therefore must resubmit the same ``output`` layer in
-``composition.layers[]`` so snapshot layer name/order still matches the
-composition and the runtime can rebuild the same structured output contract.
+"""Data-only HTTP protocol for native Pydantic AI module runs.
+
+Composition names resolve through a server-owned registry. Each module receives
+current JSON Config and restored JSON State through deps.layers[name]; Config
+and live services are never persisted. Snapshot v2 is keyed by name and has no
+ordering or generic lifecycle state. Terminal events include a state snapshot
+after native capability cleanup on success, failure and cancellation.
"""
from __future__ import annotations
@@ -40,12 +14,10 @@ from decimal import Decimal
from enum import StrEnum
from typing import Annotated, ClassVar, Final, Literal, TypeAlias
-from pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter, model_serializer, model_validator
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, TypeAdapter, model_validator
from pydantic_ai.messages import AgentStreamEvent
-from pydantic_ai.tools import DeferredToolResults
-from agenton.compositor import CompositorConfig, CompositorSessionSnapshot, LayerConfigInput, LayerNodeConfig
-from agenton.layers import ExitIntent
+from dify_agent.protocol.snapshot import SessionSnapshot
DIFY_AGENT_MODEL_LAYER_ID: Final[str] = "llm"
@@ -64,8 +36,8 @@ RunEventType = Literal[
class RunFailureType(StrEnum):
"""Stable machine-readable categories for failed Dify Agent runs.
- Run-limit failures cover execution budgets enforced by Dify Agent, not
- provider, connection, or wall-clock timeouts.
+ Run-limit failures cover Dify Agent's model-request budget and run wall-clock
+ deadline. Provider and connection timeouts retain their own error categories.
"""
AGENT_RUN_LIMIT_EXCEEDED = "agent_run_limit_exceeded"
@@ -76,83 +48,35 @@ def utc_now() -> datetime:
return datetime.now(timezone.utc)
-class LayerExitSignals(BaseModel):
- """Requested per-layer lifecycle behavior for the top-level ``on_exit`` field."""
-
- default: ExitIntent = ExitIntent.SUSPEND
- layers: dict[str, ExitIntent] = Field(default_factory=dict)
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
class RunLayerSpec(BaseModel):
- """Public graph node plus per-run layer config for one Dify Agent layer.
-
- ``name``/``type``/``deps``/``metadata`` are normalized into Agenton's
- provider-backed graph config. ``config`` is kept separate at the Agenton
- boundary and passed to ``Compositor.enter(configs=...)`` keyed by ``name``;
- existing layer config DTO instances are preserved so client code can stay
- DTO-first without being forced into raw dictionaries.
- """
-
- name: str
- type: str
- deps: dict[str, str] = Field(default_factory=dict)
- metadata: dict[str, JsonValue] = Field(default_factory=dict)
- config: LayerConfigInput = None
+ """One registered module and its current JSON configuration."""
+ name: str = Field(min_length=1)
+ config: dict[str, JsonValue] = Field(default_factory=dict)
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
class RunComposition(BaseModel):
- """Public create-run composition DTO.
+ """Module configuration; instruction order is not a public contract."""
- The public shape intentionally differs from Agenton's internal
- ``CompositorConfig`` by carrying each layer's per-run config next to its graph
- node fields. Use ``normalize_composition`` at server/runtime boundaries before
- constructing a ``Compositor``.
- """
-
- schema_version: int = 1
+ schema_version: Literal[2] = 2
layers: list[RunLayerSpec]
-
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
class CreateRunRequest(BaseModel):
- """Request body for creating one async agent run.
-
- Model/provider configuration must be supplied through the composition layer
- named by ``DIFY_AGENT_MODEL_LAYER_ID``. Optional persisted conversation
- history may be supplied through the composition layer named by
- ``DIFY_AGENT_HISTORY_LAYER_ID``. Structured output may be supplied through
- the optional composition layer named by
- ``DIFY_AGENT_OUTPUT_LAYER_ID``. ``on_exit`` defaults every active layer to
- suspend so callers receive a resumable success snapshot unless they
- explicitly request delete for one or more layers. Session snapshots do not
- preserve output-layer config, so resume requests that rely on structured
- output must include the same ``output`` layer in ``composition.layers[]`` to
- keep snapshot compatibility and rebuild the output schema. Dify tenant,
- user, and run-correlation identifiers must be submitted through a
- ``dify.execution_context`` entry in ``composition.layers[]``; there is no
- parallel top-level ``execution_context`` request field. External deferred
- tool continuation input belongs in the top-level ``deferred_tool_results``
- field rather than inside composition. Resume requests are therefore expected
- to pair a prior ``session_snapshot`` with the same logical composition so
- Agenton can rebuild the same layers and message history. For ask-human
- continuation specifically, the matching pending tool call must still exist
- in prior history state; callers should keep the history layer active across
- runs so deferred tool results can be matched against the original model
- response instead of starting a fresh user-prompt turn.
+ """Create a run using current Config and an optional state-only snapshot.
+
+ The model slot is named llm, history and output are optional reserved slots.
+ Product
+ binding/workspace lifecycle and state storage are owned by the API caller.
+ Native capabilities always release operation resources at run exit.
"""
composition: RunComposition
idempotency_key: str | None = None
metadata: dict[str, JsonValue] = Field(default_factory=dict)
- session_snapshot: CompositorSessionSnapshot | None = None
- deferred_tool_results: DeferredToolResultsPayload | None = None
- on_exit: LayerExitSignals = Field(default_factory=LayerExitSignals)
-
+ session_snapshot: SessionSnapshot | None = None
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
@@ -170,35 +94,6 @@ class CancelRunRequest(BaseModel):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-def normalize_composition(composition: RunComposition) -> tuple[CompositorConfig, dict[str, LayerConfigInput]]:
- """Split public Dify composition into Agenton's graph config and layer configs.
-
- Returns:
- A ``CompositorConfig`` containing only graph fields and a node-name keyed
- config mapping suitable for ``Compositor.enter(configs=...)``.
-
- The helper is the stable public-to-Agenton boundary: it preserves concrete
- ``LayerConfig`` DTO inputs where possible, does not accept legacy
- ``LayerNodeConfig(config=...)`` payloads, and keeps session snapshots plus
- exit signals out of graph normalization.
- """
-
- graph_config = CompositorConfig(
- schema_version=composition.schema_version,
- layers=[
- LayerNodeConfig(
- name=layer.name,
- type=layer.type,
- deps=dict(layer.deps),
- metadata=dict(layer.metadata),
- )
- for layer in composition.layers
- ],
- )
- layer_configs = {layer.name: layer.config for layer in composition.layers}
- return graph_config, layer_configs
-
-
class CreateRunResponse(BaseModel):
"""Response returned after a run has been persisted and scheduled locally."""
@@ -236,33 +131,6 @@ class EmptyRunEventData(BaseModel):
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-class DeferredToolResultsPayload(BaseModel):
- """Public JSON-safe DTO for deferred external tool results supplied on resume."""
-
- calls: dict[str, JsonValue] = Field(default_factory=dict)
- metadata: dict[str, dict[str, JsonValue]] = Field(default_factory=dict)
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
- def to_pydantic_ai(self) -> DeferredToolResults:
- """Convert the public DTO into pydantic-ai's resume input dataclass."""
- return DeferredToolResults(
- calls=dict(self.calls),
- metadata={key: dict(value) for key, value in self.metadata.items()},
- )
-
-
-class DeferredToolCallPayload(BaseModel):
- """Terminal success payload for one deferred external tool request."""
-
- tool_call_id: str
- tool_name: str
- args: JsonValue
- metadata: dict[str, JsonValue] = Field(default_factory=dict)
-
- model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
-
-
class AgentRunUsage(BaseModel):
"""Complete model usage reported for one Agent run.
@@ -295,34 +163,13 @@ class AgentRunUsage(BaseModel):
class RunSucceededEventData(BaseModel):
- """Terminal success payload for final output or deferred tool continuation."""
+ """Terminal final output and state captured after capability cleanup."""
- output: JsonValue | None = None
- deferred_tool_call: DeferredToolCallPayload | None = None
- session_snapshot: CompositorSessionSnapshot
+ output: JsonValue
+ session_snapshot: SessionSnapshot
usage: AgentRunUsage | None = None
-
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
- @model_validator(mode="after")
- def _validate_result_shape(self) -> RunSucceededEventData:
- has_output = "output" in self.model_fields_set
- has_deferred_tool_call = "deferred_tool_call" in self.model_fields_set
- if has_output == has_deferred_tool_call:
- raise ValueError("Exactly one of output or deferred_tool_call must be set")
- return self
-
- @model_serializer(mode="plain")
- def _serialize_active_result(self) -> dict[str, object]:
- data: dict[str, object] = {"session_snapshot": self.session_snapshot}
- if "output" in self.model_fields_set:
- data["output"] = self.output
- if "deferred_tool_call" in self.model_fields_set:
- data["deferred_tool_call"] = self.deferred_tool_call
- if self.usage is not None:
- data["usage"] = self.usage
- return data
-
class RunFailedEventData(BaseModel):
"""Terminal failure payload shown to polling and SSE consumers."""
@@ -330,7 +177,7 @@ class RunFailedEventData(BaseModel):
error: str
error_type: RunFailureType | None = None
reason: str | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
+ session_snapshot: SessionSnapshot | None = None
usage: AgentRunUsage | None = None
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
@@ -341,7 +188,7 @@ class RunCancelledEventData(BaseModel):
reason: str | None = None
message: str | None = None
- session_snapshot: CompositorSessionSnapshot | None = None
+ session_snapshot: SessionSnapshot | None = None
usage: AgentRunUsage | None = None
model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
@@ -417,13 +264,10 @@ __all__ = [
"CancelRunResponse",
"CreateRunRequest",
"CreateRunResponse",
- "DeferredToolCallPayload",
- "DeferredToolResultsPayload",
"DIFY_AGENT_HISTORY_LAYER_ID",
"DIFY_AGENT_MODEL_LAYER_ID",
"DIFY_AGENT_OUTPUT_LAYER_ID",
"EmptyRunEventData",
- "LayerExitSignals",
"PydanticAIStreamRunEvent",
"RUN_EVENT_ADAPTER",
"RunCancelledEvent",
@@ -441,6 +285,6 @@ __all__ = [
"RunSucceededEvent",
"RunSucceededEventData",
"RunLayerSpec",
- "normalize_composition",
+ "SessionSnapshot",
"utc_now",
]
diff --git a/dify-agent/src/dify_agent/protocol/snapshot.py b/dify-agent/src/dify_agent/protocol/snapshot.py
new file mode 100644
index 00000000000..f6cbecfd400
--- /dev/null
+++ b/dify-agent/src/dify_agent/protocol/snapshot.py
@@ -0,0 +1,126 @@
+"""State-only session snapshots with version dispatch at model validation.
+
+Configuration and live resources never belong to a snapshot. Module validators
+check the data after it is paired with the current request configuration.
+"""
+
+from typing import ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
+from pydantic_ai.messages import ModelMessagesTypeAdapter, ModelRequest, RetryPromptPart, ToolReturnPart
+
+
+_LEGACY_NAMES = frozenset(
+ {
+ "agent_soul_prompt",
+ "workflow_node_job_prompt",
+ "workflow_user_prompt",
+ "agent_app_user_prompt",
+ "execution_context",
+ "runtime",
+ "shell",
+ "config",
+ "history",
+ "llm",
+ "tools",
+ "core_tools",
+ "knowledge",
+ "ask_human",
+ "output",
+ "prompt",
+ "user_prompt",
+ }
+)
+
+
+def migrate_snapshot_v1_to_v2(snapshot: dict[str, object]) -> dict[str, object]:
+ """Convert Agenton v1 list snapshots to state-only v2 JSON data.
+
+ Legacy snapshots lack module types, so only known product slots can migrate.
+ Removed slots have no resumable state; Config-derived fields are regenerated.
+ Pending AskHuman calls are marked interrupted so native history repair can
+ close them before the first new user turn.
+
+ The input is not modified. Non-list shapes pass through for the current
+ model's validation and defaults. This function performs no persistence I/O.
+ """
+ if set(snapshot) - {"schema_version", "layers"}:
+ raise ValueError("Unknown legacy snapshot fields")
+ layers = snapshot.get("layers")
+ if not isinstance(layers, list):
+ return snapshot
+ states: dict[str, object] = {}
+ seen: set[str] = set()
+ for slot in layers:
+ if not isinstance(slot, dict) or set(slot) != {"name", "lifecycle_state", "runtime_state"}:
+ raise ValueError("Invalid legacy snapshot slot")
+ name = slot["name"]
+ if not isinstance(name, str) or name not in _LEGACY_NAMES:
+ raise ValueError(f"Unknown legacy snapshot module: {name}")
+ if name in seen:
+ raise ValueError(f"Duplicate legacy snapshot module: {name}")
+ seen.add(name)
+ lifecycle = slot["lifecycle_state"]
+ if lifecycle not in {"new", "suspended", "closed"}:
+ raise ValueError(f"Invalid legacy lifecycle state: {lifecycle}")
+ state = slot["runtime_state"]
+ if not isinstance(state, dict):
+ raise ValueError(f"Invalid legacy state for {name}")
+ state = dict(state)
+ if name == "ask_human":
+ continue
+ if lifecycle == "closed":
+ state = {}
+ elif name in {"shell", "config"}:
+ state["initialized"] = lifecycle != "new"
+ if name == "config":
+ for key in (
+ "config_context_json",
+ "config_cli_help",
+ "push_spec_semantics",
+ "push_spec_json_schema",
+ "push_spec_example",
+ ):
+ state.pop(key, None)
+ states[name] = state
+ history = states.get("history")
+ if "ask_human" in seen and isinstance(history, dict):
+ messages = ModelMessagesTypeAdapter.validate_python(history.get("messages", []))
+ if messages and messages[-1].state == "complete":
+ answered: set[str] = set()
+ for message in reversed(messages):
+ if isinstance(message, ModelRequest):
+ answered.update(
+ part.tool_call_id
+ for part in message.parts
+ if isinstance(part, (ToolReturnPart, RetryPromptPart))
+ )
+ else:
+ if any(
+ call.tool_name == "ask_human" and call.tool_call_id not in answered
+ for call in message.tool_calls
+ ):
+ # Keep every other field/message; native PAI supplies the
+ # interrupted return when a new prompt is submitted.
+ raw_messages = history["messages"]
+ history["messages"] = [
+ *raw_messages[:-1],
+ {**raw_messages[-1], "state": "interrupted"},
+ ]
+ break
+ return {"schema_version": 2, "layers": states}
+
+
+class SessionSnapshot(BaseModel):
+ """JSON state keyed by registered module name, independent of ordering."""
+
+ schema_version: Literal[2] = 2
+ layers: dict[str, dict[str, JsonValue]] = Field(default_factory=dict)
+ model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+ @model_validator(mode="before")
+ @classmethod
+ def migrate_snapshot(cls, value: object) -> object:
+ if isinstance(value, dict) and value.get("schema_version", 1) == 1:
+ return migrate_snapshot_v1_to_v2(value)
+ return value
diff --git a/dify-agent/src/dify_agent/runtime/agent_factory.py b/dify-agent/src/dify_agent/runtime/agent_factory.py
index 0161d4159fb..1bf1449c75c 100644
--- a/dify-agent/src/dify_agent/runtime/agent_factory.py
+++ b/dify-agent/src/dify_agent/runtime/agent_factory.py
@@ -1,25 +1,16 @@
-"""Pydantic AI agent construction for models supplied by Agenton layers.
-
-The run request carries model/provider selection in the layer graph. This helper
-keeps Agent construction details out of ``AgentRunRunner`` while accepting an
-already resolved Pydantic AI model from the configured model layer. Tool values
-arriving here are already transformed by Agenton's
-``PYDANTIC_AI_TRANSFORMERS`` preset. The runner passes Dify system prompts as
-run-level instructions and the context compaction capability directly to
-``Agent.run``. The caller also passes the already resolved ``output_type`` so legacy text output and the
-optional JSON Schema output layer share the same ``Agent`` construction path.
-"""
+"""Native Pydantic AI agent construction for one module run."""
from collections.abc import Sequence
from typing import Any, Final, cast
from pydantic_ai import Agent
+from pydantic_ai.capabilities import AbstractCapability
from pydantic_ai.messages import UserContent
from pydantic_ai.models import Model
from pydantic_ai.output import OutputSpec
+from pydantic_ai.toolsets import AbstractToolset
-from agenton.layers.types import PydanticAITool
-
+from dify_agent.runtime.context import Deps
DIFY_AGENT_RUN_NAME: Final[str] = "dify-agent"
@@ -27,31 +18,27 @@ DIFY_AGENT_RUN_NAME: Final[str] = "dify-agent"
def create_agent(
model: Model[Any],
*,
- tools: Sequence[PydanticAITool[object]],
+ toolsets: Sequence[AbstractToolset[Deps]],
+ capabilities: Sequence[AbstractCapability[Deps]],
output_type: OutputSpec[object] = str,
-) -> Agent[None, object]:
- """Create the pydantic-ai agent for one run.
-
- ``output_type`` is resolved by the runtime after entering the Agenton run so
- validation and execution both honor the same optional structured output
- contract. For structured output runs the type inside ``output_type`` already
- carries the Pydantic hooks needed for schema exposure and runtime validation,
- so agent construction does not need to register a separate validator.
- """
- # TODO: propagate roster name, so gen_ai.agent.name can pick that up
+) -> Agent[Deps, object]:
+ """Use native instructions, tool dispatch, ordering and capability hooks."""
agent = cast(
- Agent[None, object],
- Agent(model, name=DIFY_AGENT_RUN_NAME, output_type=output_type, tools=tools),
+ Agent[Deps, object],
+ Agent(
+ model,
+ name=DIFY_AGENT_RUN_NAME,
+ deps_type=Deps,
+ output_type=output_type,
+ toolsets=toolsets,
+ capabilities=capabilities,
+ ),
)
agent.instrument = False
return agent
def normalize_user_input(user_prompts: Sequence[UserContent]) -> str | Sequence[UserContent]:
- """Return the pydantic-ai run input while preserving multi-part prompts."""
if len(user_prompts) == 1 and isinstance(user_prompts[0], str):
return user_prompts[0]
return list(user_prompts)
-
-
-__all__ = ["DIFY_AGENT_RUN_NAME", "create_agent", "normalize_user_input"]
diff --git a/dify-agent/src/dify_agent/runtime/agenton_validation.py b/dify-agent/src/dify_agent/runtime/agenton_validation.py
deleted file mode 100644
index 3522e16b081..00000000000
--- a/dify-agent/src/dify_agent/runtime/agenton_validation.py
+++ /dev/null
@@ -1,28 +0,0 @@
-"""Shared validation helpers for Agenton-backed request boundaries.
-
-Most bad Dify Agent inputs surface from Agenton as ``KeyError``, ``TypeError``,
-or ``ValueError`` while graph config, per-run layer config, and session snapshot
-DTOs are being validated. One smaller class of request-shaped failures appears a
-bit later, during ``Compositor.enter(...)`` before the body of the entered run
-executes: session snapshots may contain lifecycle states such as ``CLOSED`` that
-are serializable but not enterable. Agenton reports those as ``RuntimeError``.
-
-Dify Agent intentionally translates only these known enter-time runtime errors
-into public request-validation errors. Other runtime failures still represent
-execution bugs or infrastructure problems and must not be downgraded to client
-input errors.
-"""
-
-_ENTER_VALIDATION_RUNTIME_ERROR_FRAGMENTS = (
- "ACTIVE snapshots are not allowed.",
- "CLOSED snapshots cannot be entered.",
-)
-
-
-def is_agenton_enter_validation_runtime_error(exc: RuntimeError) -> bool:
- """Return whether ``exc`` is a known Agenton enter-time input failure."""
- message = str(exc)
- return any(fragment in message for fragment in _ENTER_VALIDATION_RUNTIME_ERROR_FRAGMENTS)
-
-
-__all__ = ["is_agenton_enter_validation_runtime_error"]
diff --git a/dify-agent/src/dify_agent/runtime/compaction.py b/dify-agent/src/dify_agent/runtime/compaction.py
index b1e40e5f436..3df21baf21f 100644
--- a/dify-agent/src/dify_agent/runtime/compaction.py
+++ b/dify-agent/src/dify_agent/runtime/compaction.py
@@ -8,6 +8,7 @@ unused ``max_tokens=1`` values below solely to satisfy that validation; they are
not one-token Dify policy thresholds.
"""
+from dify_agent.runtime.context import Deps
from pydantic_ai.settings import ModelSettings
from pydantic_ai_harness.compaction import ClearToolResults, SummarizingCompaction, TieredCompaction
@@ -16,7 +17,7 @@ def build_compaction_capability(
*,
context_window_tokens: int | None,
model_settings: ModelSettings | None,
-) -> TieredCompaction[None] | None:
+) -> TieredCompaction[Deps] | None:
"""Build compaction for the effective model window, or disable it when unknown."""
if context_window_tokens is None:
return None
diff --git a/dify-agent/src/dify_agent/runtime/compositor_factory.py b/dify-agent/src/dify_agent/runtime/compositor_factory.py
deleted file mode 100644
index a22df749ea6..00000000000
--- a/dify-agent/src/dify_agent/runtime/compositor_factory.py
+++ /dev/null
@@ -1,185 +0,0 @@
-"""Safe Agenton compositor construction for API-submitted configs.
-
-Only explicitly allowed provider type ids are constructible here. The default
-provider set contains prompt layers, the optional pydantic-ai history layer, the
-state-free Dify structured output layer, the optional Dify ask-human layer, the
-Dify execution-context and runtime-resource layers, the stateful Dify shell
-layer, and the Dify plugin/knowledge business-layer family:
-
-- ``dify.config`` for Agent Soul-backed config assets + eager pull,
-- ``dify.execution_context`` for shared tenant/user/run daemon context,
-- ``dify.runtime`` for operation-scoped RuntimeLease acquisition,
-- ``dify.shell`` for command/file capabilities from the active RuntimeLease,
-- ``dify.user_prompt`` for structured text-plus-image user turns,
-- ``dify.plugin.llm`` for plugin-backed model selection,
-- ``dify.plugin.tools`` for prepared plugin tool exposure, and
-- ``dify.core.tools`` for API-routed Dify tool exposure, and
-- ``dify.knowledge_base`` for inner-API-backed knowledge search tools.
-
-Public DTOs provide Dify context plus plugin/model/tool data, while server-only
-plugin daemon settings and Dify API inner settings are injected through provider
-factories. The deployment-selected runtime backend profile is injected only
-into the Runtime layer. Shell receives Agent Stub settings and consumes the
-active lease's data plane. The resulting ``Compositor``
-remains Agenton state-only at the snapshot boundary: live resources such as
-HTTP clients are injected by runtime-owned providers, may be held on active
-layer instances inside ``resource_context()``, and never enter session
-snapshots.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping, Sequence
-from typing import Any
-
-from pydantic_ai.messages import UserContent
-
-from agenton.compositor import Compositor, CompositorConfig, LayerProvider, LayerProviderInput
-from agenton.layers.types import AllPromptTypes, AllToolTypes, AllUserPromptTypes, PydanticAIPrompt, PydanticAITool
-from agenton_collections.layers.pydantic_ai import PydanticAIHistoryLayer
-from agenton_collections.layers.plain.basic import PromptLayer
-from agenton_collections.transformers.pydantic_ai import PYDANTIC_AI_TRANSFORMERS
-from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory
-from dify_agent.layers.ask_human.layer import DifyAskHumanLayer
-from dify_agent.layers.config.layer import DifyConfigLayer
-from dify_agent.layers.dify_core_tools.configs import DifyCoreToolsLayerConfig
-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer
-from dify_agent.layers.dify_plugin.configs import DifyPluginLLMLayerConfig, DifyPluginToolsLayerConfig
-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer
-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer
-from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-from dify_agent.layers.knowledge.configs import DifyKnowledgeBaseLayerConfig
-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer
-from dify_agent.layers.output.output_layer import DifyOutputLayer
-from dify_agent.layers.runtime.configs import DifyRuntimeLayerConfig
-from dify_agent.layers.runtime.layer import DifyRuntimeLayer
-from dify_agent.layers.shell.configs import DifyShellLayerConfig
-from dify_agent.layers.shell.layer import DifyShellLayer
-from dify_agent.layers.user_prompt.layer import DifyUserPromptLayer
-from dify_agent.runtime_backend import RuntimeBackendProfile
-
-type DifyAgentLayerProvider = LayerProvider[Any]
-
-
-def create_default_layer_providers(
- *,
- plugin_daemon_url: str = "http://localhost:5002",
- plugin_daemon_api_key: str = "",
- inner_api_url: str = "http://localhost:5001",
- inner_api_key: str = "",
- runtime_backend_profile: RuntimeBackendProfile | None = None,
- shell_redact_patterns: list[str] | None = None,
- agent_stub_api_base_url: str | None = None,
- agent_stub_token_factory: ShellAgentStubTokenFactory | None = None,
-) -> tuple[DifyAgentLayerProvider, ...]:
- """Return the server provider set of safe config-constructible layers."""
- providers: list[DifyAgentLayerProvider] = [
- LayerProvider.from_layer_type(PromptLayer),
- LayerProvider.from_layer_type(DifyUserPromptLayer),
- LayerProvider.from_layer_type(PydanticAIHistoryLayer),
- LayerProvider.from_layer_type(DifyOutputLayer),
- LayerProvider.from_layer_type(DifyAskHumanLayer),
- LayerProvider.from_layer_type(DifyConfigLayer),
- LayerProvider.from_factory(
- layer_type=DifyExecutionContextLayer,
- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(
- DifyExecutionContextLayerConfig.model_validate(config),
- daemon_url=plugin_daemon_url,
- daemon_api_key=plugin_daemon_api_key,
- ),
- ),
- LayerProvider.from_factory(
- layer_type=DifyShellLayer,
- create=lambda config: DifyShellLayer.from_config_with_settings(
- DifyShellLayerConfig.model_validate(config),
- shell_redact_patterns=shell_redact_patterns or [],
- agent_stub_api_base_url=agent_stub_api_base_url,
- agent_stub_token_factory=agent_stub_token_factory,
- ),
- ),
- LayerProvider.from_factory(
- layer_type=DifyPluginLLMLayer,
- create=lambda config: DifyPluginLLMLayer.from_config_with_settings(
- DifyPluginLLMLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- ),
- ),
- LayerProvider.from_factory(
- layer_type=DifyPluginToolsLayer,
- create=lambda config: DifyPluginToolsLayer.from_config_with_settings(
- DifyPluginToolsLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- ),
- ),
- LayerProvider.from_factory(
- layer_type=DifyCoreToolsLayer,
- create=lambda config: DifyCoreToolsLayer.from_config_with_settings(
- DifyCoreToolsLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- ),
- ),
- LayerProvider.from_factory(
- layer_type=DifyKnowledgeBaseLayer,
- create=lambda config: DifyKnowledgeBaseLayer.from_config_with_settings(
- DifyKnowledgeBaseLayerConfig.model_validate(config),
- inner_api_url=inner_api_url,
- inner_api_key=inner_api_key,
- ),
- ),
- ]
- if runtime_backend_profile is not None:
- providers.extend(
- [
- LayerProvider.from_factory(
- layer_type=DifyRuntimeLayer,
- create=lambda config: DifyRuntimeLayer.from_config_with_backend(
- DifyRuntimeLayerConfig.model_validate(config),
- backend=runtime_backend_profile.execution_bindings,
- ),
- ),
- ]
- )
- return tuple(providers)
-
-
-def build_pydantic_ai_compositor(
- config: CompositorConfig,
- *,
- providers: Sequence[LayerProviderInput],
- node_providers: Mapping[str, LayerProviderInput] | None = None,
-) -> Compositor[
- PydanticAIPrompt[object],
- PydanticAITool[object],
- AllPromptTypes,
- AllToolTypes,
- UserContent,
- AllUserPromptTypes,
-]:
- """Build a Pydantic AI-ready compositor from a validated graph config.
-
- Prompt, user prompt, and tool conversion is delegated to Agenton's shared
- pydantic-ai transformer preset so Dify Agent does not duplicate conversion
- logic for plain and pydantic-ai layer families. Callers must pass the already
- selected provider set explicitly so provider defaulting stays at outer runtime
- boundaries rather than being duplicated here.
- """
- return Compositor[
- PydanticAIPrompt[object],
- PydanticAITool[object],
- AllPromptTypes,
- AllToolTypes,
- UserContent,
- AllUserPromptTypes,
- ].from_config(
- config,
- providers=providers,
- node_providers=node_providers,
- **PYDANTIC_AI_TRANSFORMERS,
- )
-
-
-__all__ = ["DifyAgentLayerProvider", "build_pydantic_ai_compositor", "create_default_layer_providers"]
diff --git a/dify-agent/src/dify_agent/runtime/context.py b/dify-agent/src/dify_agent/runtime/context.py
new file mode 100644
index 00000000000..55a1c672324
--- /dev/null
+++ b/dify-agent/src/dify_agent/runtime/context.py
@@ -0,0 +1,56 @@
+"""Dependencies for native Pydantic AI modules.
+
+``layers`` is the sole source of module config and persisted state. Models are
+validated copies and state changes must be dumped back explicitly. Services are
+borrowed from the server lifespan; resources exist only inside one native run
+and are closed by the capability that acquired them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, TypedDict
+
+import httpx
+from pydantic import JsonValue
+
+from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory
+from dify_agent.runtime_backend import RuntimeBackendProfile, RuntimeLease
+
+if TYPE_CHECKING:
+ from dify_agent.layers.shell.layer import ShellSession
+
+
+class LayerData(TypedDict):
+ config: dict[str, JsonValue]
+ state: dict[str, JsonValue]
+
+
+@dataclass
+class Services:
+ """Lifespan-owned infrastructure borrowed by every run."""
+
+ plugin_daemon_http_client: httpx.AsyncClient
+ dify_api_http_client: httpx.AsyncClient
+ plugin_daemon_url: str = "http://localhost:5002"
+ plugin_daemon_api_key: str = field(default="", repr=False)
+ inner_api_url: str = "http://localhost:5001"
+ inner_api_key: str = field(default="", repr=False)
+ runtime_backend_profile: RuntimeBackendProfile | None = None
+ shell_redact_patterns: list[str] = field(default_factory=list)
+ agent_stub_api_base_url: str | None = None
+ agent_stub_token_factory: ShellAgentStubTokenFactory | None = None
+
+
+@dataclass
+class RunResources:
+ leases: dict[str, RuntimeLease] = field(default_factory=dict)
+ shells: dict[str, ShellSession] = field(default_factory=dict)
+
+
+@dataclass
+class Deps:
+ layers: dict[str, LayerData]
+ services: Services
+ run_id: str
+ resources: RunResources = field(default_factory=RunResources)
diff --git a/dify-agent/src/dify_agent/runtime/event_sink.py b/dify-agent/src/dify_agent/runtime/event_sink.py
index 161e1a75fde..ea68a3e1948 100644
--- a/dify-agent/src/dify_agent/runtime/event_sink.py
+++ b/dify-agent/src/dify_agent/runtime/event_sink.py
@@ -10,15 +10,14 @@ implements the same contract with Redis streams in
from collections import defaultdict
from dataclasses import dataclass
-from typing import Protocol, TypeAlias, cast
+from typing import Protocol, TypeAlias
from pydantic import JsonValue
from pydantic_ai.messages import AgentStreamEvent
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.protocol.schemas import (
AgentRunUsage,
- DeferredToolCallPayload,
EmptyRunEventData,
PydanticAIStreamRunEvent,
RunEvent,
@@ -33,7 +32,6 @@ from dify_agent.protocol.schemas import (
)
-_UNSET = object()
TerminalRunEvent: TypeAlias = RunSucceededEvent | RunFailedEvent
NonTerminalRunEvent: TypeAlias = RunStartedEvent | PydanticAIStreamRunEvent
@@ -146,26 +144,15 @@ async def emit_run_succeeded(
sink: RunEventSink,
*,
run_id: str,
- output: JsonValue | None | object = _UNSET,
- deferred_tool_call: DeferredToolCallPayload | object = _UNSET,
- session_snapshot: CompositorSessionSnapshot,
+ output: JsonValue,
+ session_snapshot: SessionSnapshot,
usage: AgentRunUsage | None = None,
) -> RunFinalizationResult:
- """Finalize a run as succeeded with output or deferred continuation.
-
- Callers must activate exactly one result branch. ``_UNSET`` is used instead
- of ``None`` to preserve the distinction between an omitted inactive branch
- and an active ``output`` branch whose JSON value is explicitly ``null``.
- Without that sentinel, ``output=None`` would be indistinguishable from
- “output field absent”, which would break nullable-success payloads.
- """
- data: dict[str, JsonValue | DeferredToolCallPayload | CompositorSessionSnapshot | AgentRunUsage | None] = {
+ """Finalize a successful run, including explicitly null output."""
+ data: dict[str, JsonValue | SessionSnapshot | AgentRunUsage | None] = {
"session_snapshot": session_snapshot,
}
- if output is not _UNSET:
- data["output"] = cast(JsonValue | None, output)
- if deferred_tool_call is not _UNSET:
- data["deferred_tool_call"] = cast(DeferredToolCallPayload, deferred_tool_call)
+ data["output"] = output
if usage is not None:
data["usage"] = usage
@@ -185,7 +172,7 @@ async def emit_run_failed(
error: str,
error_type: RunFailureType | None = None,
reason: str | None = None,
- session_snapshot: CompositorSessionSnapshot | None = None,
+ session_snapshot: SessionSnapshot | None = None,
usage: AgentRunUsage | None = None,
) -> RunFinalizationResult:
"""Finalize a run with a failed terminal event."""
diff --git a/dify-agent/src/dify_agent/runtime/history.py b/dify-agent/src/dify_agent/runtime/history.py
deleted file mode 100644
index fc61e9cf3cc..00000000000
--- a/dify-agent/src/dify_agent/runtime/history.py
+++ /dev/null
@@ -1,117 +0,0 @@
-"""Helpers for optional Dify Agent history-layer integration.
-
-Dify Agent keeps pydantic-ai conversation history as an optional Agenton layer
-named ``history``. Current system instructions belong to each run and are never
-stored. Once Pydantic AI binds and builds messages in the run capture, its
-complete captured history replaces the layer for every terminal outcome,
-including interrupted runs. A failure or cancellation before the capture
-contains messages preserves the previously restored history. When a run is
-interrupted with tool calls the model returned but the run never executed, the
-stored history records that the response was cut short so the next run can close
-those calls out instead of refusing a new user prompt.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-from dataclasses import replace
-from typing import Protocol
-
-from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse
-
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID, PydanticAIHistoryLayer
-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID
-from dify_agent.protocol.schemas import RunComposition
-
-
-class SupportsHistoryLayerLookup(Protocol):
- """Minimal entered-run surface needed by the history helper."""
-
- def get_layer(self, name: str, layer_type: type[PydanticAIHistoryLayer]) -> PydanticAIHistoryLayer:
- """Return a typed layer instance or raise lookup/type errors."""
- ...
-
-
-def validate_history_layer_composition(composition: RunComposition) -> None:
- """Reject unsupported public history-layer graph shapes."""
- history_layers = [layer for layer in composition.layers if layer.type == PYDANTIC_AI_HISTORY_LAYER_TYPE_ID]
- if not history_layers:
- return
-
- if len(history_layers) > 1:
- names = ", ".join(layer.name for layer in history_layers)
- raise ValueError(
- f"Only one '{PYDANTIC_AI_HISTORY_LAYER_TYPE_ID}' layer is supported, named "
- f"'{DIFY_AGENT_HISTORY_LAYER_ID}'. Found layers: {names}."
- )
-
- history_layer = history_layers[0]
- if history_layer.name != DIFY_AGENT_HISTORY_LAYER_ID:
- raise ValueError(
- f"Layer type '{PYDANTIC_AI_HISTORY_LAYER_TYPE_ID}' must use reserved layer name "
- f"'{DIFY_AGENT_HISTORY_LAYER_ID}', got '{history_layer.name}'."
- )
-
- if history_layer.deps:
- dependency_names = ", ".join(sorted(history_layer.deps))
- raise ValueError(
- f"Layer type '{PYDANTIC_AI_HISTORY_LAYER_TYPE_ID}' does not support dependencies; "
- f"got dependency keys: {dependency_names}."
- )
-
-
-def get_history_layer(run: SupportsHistoryLayerLookup) -> PydanticAIHistoryLayer | None:
- """Return the active history layer when the reserved slot is present."""
- try:
- return run.get_layer(DIFY_AGENT_HISTORY_LAYER_ID, PydanticAIHistoryLayer)
- except KeyError:
- return None
-
-
-def replace_run_history(
- history_layer: PydanticAIHistoryLayer | None,
- messages: Sequence[ModelMessage],
- *,
- interrupted: bool = False,
-) -> None:
- """Persist a run's captured history without transient instructions.
-
- Set ``interrupted`` when the run did not reach a terminal result, so tool calls the run
- never got to execute are marked as such for the next run.
- """
- if history_layer is None:
- return
- persistent_messages: list[ModelMessage] = [
- replace(message, instructions=None) if isinstance(message, ModelRequest) else message for message in messages
- ]
- if interrupted:
- persistent_messages = _mark_trailing_tool_calls_interrupted(persistent_messages)
- history_layer.replace_messages(persistent_messages)
-
-
-def _mark_trailing_tool_calls_interrupted(messages: list[ModelMessage]) -> list[ModelMessage]:
- """Record that a final response's tool calls were never executed.
-
- A run cancelled between the model returning tool calls and the first tool result leaves a
- ``'complete'`` response whose calls have no matching result. Pydantic AI closes such calls
- out with synthesized returns on the next run only when that tail is marked
- ``'interrupted'``; otherwise it rejects the next user prompt and the conversation cannot
- continue. A run that ends in ``DeferredToolRequests`` keeps its open calls, which is why
- this is applied to interrupted runs only.
- """
- if not messages:
- return messages
- last_message = messages[-1]
- if not isinstance(last_message, ModelResponse) or last_message.state != "complete":
- return messages
- if not last_message.tool_calls:
- return messages
- return [*messages[:-1], replace(last_message, state="interrupted")]
-
-
-__all__ = [
- "SupportsHistoryLayerLookup",
- "get_history_layer",
- "replace_run_history",
- "validate_history_layer_composition",
-]
diff --git a/dify-agent/src/dify_agent/runtime/layer_exit_signals.py b/dify-agent/src/dify_agent/runtime/layer_exit_signals.py
deleted file mode 100644
index 3636b898368..00000000000
--- a/dify-agent/src/dify_agent/runtime/layer_exit_signals.py
+++ /dev/null
@@ -1,46 +0,0 @@
-"""Validation and application of request-level Agenton layer exit signals.
-
-HTTP requests carry data-only lifecycle intent in the top-level ``on_exit``
-field. The runtime validates signal keys against the built compositor before a
-run is persisted or entered, then applies the resolved intent to the active
-``CompositorRun`` after entry because Agenton initializes each run slot with a
-delete-on-exit intent.
-"""
-
-from typing import Any
-
-from agenton.compositor import Compositor, CompositorRun
-from agenton.layers import ExitIntent
-from dify_agent.protocol.schemas import LayerExitSignals
-
-
-def validate_layer_exit_signals(
- compositor: Compositor[Any, Any, Any, Any, Any, Any],
- signals: LayerExitSignals,
-) -> None:
- """Raise ``ValueError`` when ``signals`` mention layers absent from ``compositor``."""
- known_layer_ids = {node.name for node in compositor.nodes}
- unknown_layer_ids = set(signals.layers) - known_layer_ids
- if not unknown_layer_ids:
- return
-
- names = ", ".join(sorted(unknown_layer_ids))
- raise ValueError(f"on_exit.layers references unknown layer ids: {names}.")
-
-
-def apply_layer_exit_signals(
- run: CompositorRun[Any, Any, Any, Any, Any, Any],
- signals: LayerExitSignals,
-) -> None:
- """Apply ``signals`` to active run slots for the current compositor entry."""
- for layer_id in run.slots:
- intent = signals.layers.get(layer_id, signals.default)
- if intent is ExitIntent.SUSPEND:
- run.suspend_layer_on_exit(layer_id)
- elif intent is ExitIntent.DELETE:
- run.delete_layer_on_exit(layer_id)
- else:
- raise ValueError(f"Unsupported layer exit intent: {intent!r}.")
-
-
-__all__ = ["apply_layer_exit_signals", "validate_layer_exit_signals"]
diff --git a/dify-agent/src/dify_agent/runtime/modules.py b/dify-agent/src/dify_agent/runtime/modules.py
new file mode 100644
index 00000000000..959572ab94b
--- /dev/null
+++ b/dify-agent/src/dify_agent/runtime/modules.py
@@ -0,0 +1,139 @@
+"""Allowlisted name-to-module registry and JSON state loading.
+
+Modules export Config, State and exactly one native Capability or Toolset. All
+configuration, state and references are checked before a run performs I/O. The
+registry is server-owned; HTTP callers never supply import paths or live objects.
+"""
+
+from collections.abc import Mapping
+from types import ModuleType
+from typing import cast
+
+from pydantic import BaseModel
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.toolsets import AbstractToolset
+
+from dify_agent.layers import history
+from dify_agent.layers.prompt import layer as prompt
+from dify_agent.layers.config import layer as config
+from dify_agent.layers.dify_core_tools import layer as core_tools
+from dify_agent.layers.dify_plugin import llm_layer as llm, tools_layer as plugin_tools
+from dify_agent.layers.execution_context import layer as execution_context
+from dify_agent.layers.knowledge import layer as knowledge
+from dify_agent.layers.output import output_layer as output
+from dify_agent.layers.runtime import layer as runtime
+from dify_agent.layers.shell import layer as shell
+from dify_agent.layers.user_prompt import layer as user_prompt
+from dify_agent.protocol.schemas import CreateRunRequest
+from dify_agent.protocol.snapshot import SessionSnapshot
+from dify_agent.runtime.context import Deps, LayerData, Services
+
+
+REGISTRY: dict[str, ModuleType] = {
+ "agent_soul_prompt": prompt,
+ "workflow_node_job_prompt": prompt,
+ "workflow_user_prompt": prompt,
+ "agent_app_user_prompt": user_prompt,
+ "prompt": prompt,
+ "user_prompt": user_prompt,
+ "execution_context": execution_context,
+ "runtime": runtime,
+ "shell": shell,
+ "config": config,
+ "history": history,
+ "llm": llm,
+ "tools": plugin_tools,
+ "core_tools": core_tools,
+ "knowledge": knowledge,
+ "output": output,
+}
+
+_REFERENCES: dict[ModuleType, dict[str, ModuleType]] = {
+ llm: {"execution_context": execution_context},
+ plugin_tools: {"execution_context": execution_context, "shell": shell},
+ core_tools: {"execution_context": execution_context},
+ knowledge: {"execution_context": execution_context},
+ shell: {"runtime": runtime, "execution_context": execution_context},
+ config: {"shell": shell},
+}
+
+
+def load_modules(
+ request: CreateRunRequest, services: Services, run_id: str, *, registry: Mapping[str, ModuleType] = REGISTRY
+) -> Deps:
+ """Create independent validated JSON data using current Config and saved State.
+
+ Optional modules may be added or removed between runs. Retained unknown state
+ names are rejected, while known removed slots are omitted from the new
+ snapshot. Legacy migration happens at the snapshot DTO boundary.
+ """
+ names = [spec.name for spec in request.composition.layers]
+ if len(set(names)) != len(names):
+ raise ValueError("Module names must be unique")
+ if "llm" not in names:
+ raise ValueError("Missing required 'llm' module")
+ state = request.session_snapshot.layers if request.session_snapshot is not None else {}
+ unknown = state.keys() - registry.keys()
+ if unknown:
+ raise ValueError(f"Unknown snapshot modules: {', '.join(sorted(unknown))}")
+ layers: dict[str, LayerData] = {}
+ configs: dict[str, BaseModel] = {}
+ for spec in request.composition.layers:
+ module = registry.get(spec.name)
+ if module is None:
+ raise ValueError(f"Unknown registered module: {spec.name}")
+ config_type = cast(type[BaseModel], module.Config)
+ state_type = cast(type[BaseModel], module.State)
+ has_capability = hasattr(module, "Capability")
+ has_toolset = hasattr(module, "Toolset")
+ if has_capability == has_toolset:
+ raise TypeError(f"Module {spec.name} must export exactly one Capability or Toolset")
+ implementation = module.Capability if has_capability else module.Toolset
+ expected = AbstractCapability if has_capability else AbstractToolset
+ if not issubclass(implementation, expected):
+ raise TypeError(f"Module {spec.name} must use native Pydantic AI components")
+ cfg = config_type.model_validate(spec.config)
+ restored = state_type.model_validate(state.get(spec.name, {}))
+ configs[spec.name] = cfg
+ layers[spec.name] = {"config": cfg.model_dump(mode="json"), "state": restored.model_dump(mode="json")}
+ for name, cfg in configs.items():
+ module = registry[name]
+ for field, expected_module in _REFERENCES.get(module, {}).items():
+ target = cast(str | None, layers[name]["config"][field])
+ if target is None:
+ continue
+ if target not in layers or registry[target] is not expected_module:
+ raise ValueError(
+ f"Module {name} reference {field} must name a configured {expected_module.__name__} module"
+ )
+ if module is runtime and services.runtime_backend_profile is None:
+ raise ValueError("Runtime module requires a configured runtime backend")
+ if module is plugin_tools:
+ for tool in cast(plugin_tools.Config, cfg).tools:
+ plugin_tools._validate_required_hidden_parameters(tool, tool.parameters)
+ if module is knowledge:
+ target = cast(knowledge.Config, cfg).execution_context
+ knowledge._build_caller_context(configs[target])
+ return Deps(layers=layers, services=services, run_id=run_id)
+
+
+def create_modules(
+ deps: Deps, *, registry: Mapping[str, ModuleType] = REGISTRY
+) -> dict[str, AbstractCapability[Deps] | AbstractToolset[Deps]]:
+ """Construct fresh native instances for this run; no instance is restored."""
+ return {
+ name: (
+ registry[name].Capability(name) if hasattr(registry[name], "Capability") else registry[name].Toolset(name)
+ )
+ for name in deps.layers
+ }
+
+
+def snapshot_modules(deps: Deps, *, registry: Mapping[str, ModuleType] = REGISTRY) -> SessionSnapshot:
+ """Validate and copy final state after resource cleanup, excluding all Config."""
+ return SessionSnapshot(
+ layers={
+ name: registry[name].State.model_validate(entry["state"]).model_dump(mode="json")
+ for name, entry in deps.layers.items()
+ }
+ )
diff --git a/dify-agent/src/dify_agent/runtime/observability.py b/dify-agent/src/dify_agent/runtime/observability.py
index 8933dea279c..b7b4d0de3e6 100644
--- a/dify-agent/src/dify_agent/runtime/observability.py
+++ b/dify-agent/src/dify_agent/runtime/observability.py
@@ -3,7 +3,7 @@ from __future__ import annotations
import asyncio
from collections.abc import Sequence
from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Final, Literal
+from typing import TYPE_CHECKING, Any, Final, Literal, override
from opentelemetry.context import Context
from opentelemetry.sdk.trace import ReadableSpan
@@ -63,6 +63,7 @@ class IsolatedTracerProvider(TracerProvider):
client: Logfire
preserve_external_parent: bool = False
+ @override
def get_tracer(
self,
instrumenting_module_name: str,
@@ -97,6 +98,7 @@ class _IsolatedTracer(Tracer):
return context
return set_span_in_context(INVALID_SPAN, context)
+ @override
def start_span(
self,
name: str,
@@ -119,6 +121,7 @@ class _IsolatedTracer(Tracer):
set_status_on_exception=set_status_on_exception,
)
+ @override
def start_as_current_span(
self,
name: str,
@@ -151,6 +154,7 @@ class RunScopedTracerProvider(TracerProvider):
delegate: TracerProvider
attributes: tuple[tuple[str, str], ...]
+ @override
def get_tracer(
self,
instrumenting_module_name: str,
@@ -175,6 +179,7 @@ class _RunScopedTracer(Tracer):
def _run_attributes(self, attributes: Attributes) -> Attributes:
return {**(attributes or {}), **dict(self.attributes)}
+ @override
def start_span(
self,
name: str,
@@ -197,6 +202,7 @@ class _RunScopedTracer(Tracer):
set_status_on_exception=set_status_on_exception,
)
+ @override
def start_as_current_span(
self,
name: str,
diff --git a/dify-agent/src/dify_agent/runtime/output_type.py b/dify-agent/src/dify_agent/runtime/output_type.py
deleted file mode 100644
index a8e12cfd6ff..00000000000
--- a/dify-agent/src/dify_agent/runtime/output_type.py
+++ /dev/null
@@ -1,92 +0,0 @@
-"""Validate and resolve the optional structured output layer.
-
-Dify Agent keeps structured output outside Agenton's prompt/tool aggregation.
-That means the request boundary must validate the public composition shape
-before entering Agenton, while the entered-run helper resolves a complete output
-contract containing the model-facing output type. The type itself carries the
-custom Pydantic hooks needed for schema exposure and runtime validation, so the
-runtime does not need a separate validator callback. Missing output layers
-preserve the legacy plain-text ``str`` output contract.
-"""
-
-from typing import Protocol
-
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID
-from dify_agent.layers.output.output_layer import DifyOutputContract, DifyOutputLayer
-from dify_agent.protocol import DIFY_AGENT_OUTPUT_LAYER_ID
-from dify_agent.protocol.schemas import RunComposition
-
-
-class SupportsOutputLayerLookup(Protocol):
- """Minimal run surface needed to resolve the optional output layer."""
-
- def get_layer(self, name: str, layer_type: type[DifyOutputLayer]) -> DifyOutputLayer:
- """Return a typed layer instance or raise lookup/type errors."""
- ...
-
-
-def validate_output_layer_composition(composition: RunComposition) -> None:
- """Reject unsupported public output-layer graph shapes.
-
- The proposal reserves the node name ``output`` for the single supported
- ``dify.output`` layer. Validating this directly from
- ``CreateRunRequest.composition.layers`` keeps bad requests from silently
- falling back to text output after entering Agenton.
-
- Raises:
- ValueError: If more than one ``dify.output`` layer is declared or if the
- single ``dify.output`` layer does not use the reserved node name
- ``output``.
- """
- output_layer_names = [layer.name for layer in composition.layers if layer.type == DIFY_OUTPUT_LAYER_TYPE_ID]
- if not output_layer_names:
- return
-
- if len(output_layer_names) > 1:
- names = ", ".join(output_layer_names)
- raise ValueError(
- f"Only one '{DIFY_OUTPUT_LAYER_TYPE_ID}' layer is supported, named '{DIFY_AGENT_OUTPUT_LAYER_ID}'. "
- f"Found layers: {names}."
- )
-
- output_layer_name = output_layer_names[0]
- if output_layer_name != DIFY_AGENT_OUTPUT_LAYER_ID:
- raise ValueError(
- f"Layer type '{DIFY_OUTPUT_LAYER_TYPE_ID}' must use reserved layer name "
- f"'{DIFY_AGENT_OUTPUT_LAYER_ID}', got '{output_layer_name}'."
- )
-
-
-_TEXT_OUTPUT_CONTRACT = DifyOutputContract(output_type=str)
-
-
-def resolve_run_output_contract(run: SupportsOutputLayerLookup) -> DifyOutputContract:
- """Return the run's configured pydantic-ai output contract.
-
- When the conventionally named output layer is absent, the runtime keeps the
- existing plain-text behavior by returning a contract whose ``output_type`` is
- ``str``. This helper assumes the
- public composition has already passed ``validate_output_layer_composition``;
- its remaining responsibility is to type-check the reserved ``output`` slot
- after compositor entry and build the validated output type from the layer
- config.
-
- Raises:
- TypeError: If a layer named ``output`` exists but is not a
- ``DifyOutputLayer``.
- ValueError: If the output layer exists but its JSON Schema cannot be
- converted into a supported pydantic-ai structured output contract.
- """
- try:
- output_layer = run.get_layer(DIFY_AGENT_OUTPUT_LAYER_ID, DifyOutputLayer)
- except KeyError:
- return _TEXT_OUTPUT_CONTRACT
- return output_layer.build_output_contract()
-
-
-__all__ = [
- "DifyOutputContract",
- "SupportsOutputLayerLookup",
- "resolve_run_output_contract",
- "validate_output_layer_composition",
-]
diff --git a/dify-agent/src/dify_agent/runtime/run_scheduler.py b/dify-agent/src/dify_agent/runtime/run_scheduler.py
index db3592b3cd1..dfebfdadade 100644
--- a/dify-agent/src/dify_agent/runtime/run_scheduler.py
+++ b/dify-agent/src/dify_agent/runtime/run_scheduler.py
@@ -8,7 +8,7 @@ handoff. If the process crashes, currently active runs are lost until an externa
operator marks or retries them.
Create-run requests are accepted once the scheduler is not stopping and storage
can persist the run record. Request-shaped execution failures are left to
-``AgentRunRunner`` so bad compositions, ``on_exit`` policies, prompts,
+``AgentRunRunner`` so bad compositions, prompts,
structured-output schemas, or session snapshots become asynchronous
``run_failed`` outcomes instead of synchronous HTTP rejections.
"""
@@ -18,12 +18,11 @@ import logging
from collections.abc import Callable
from typing import Protocol
-import httpx
-from agenton.compositor import CompositorSessionSnapshot, LayerProviderInput
+from dify_agent.protocol.snapshot import SessionSnapshot
+from dify_agent.runtime.context import Services
from dify_agent.protocol.schemas import AgentRunUsage, CancelRunRequest, CancelRunResponse, CreateRunRequest, RunStatus
from dify_agent.runtime.cancellation import RunCancellationIntent
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
from dify_agent.runtime.event_coalescer import (
DEFAULT_TEXT_DELTA_FLUSH_INTERVAL_SECONDS,
DEFAULT_TEXT_DELTA_MAX_CHARS,
@@ -68,7 +67,7 @@ class RunStore(RunEventSink, Protocol):
run_id: str,
intent: RunCancellationIntent,
*,
- session_snapshot: CompositorSessionSnapshot | None = None,
+ session_snapshot: SessionSnapshot | None = None,
usage: AgentRunUsage | None = None,
) -> RunFinalizationResult:
"""Publish cancellation after the owner runner has exited."""
@@ -79,7 +78,7 @@ class RunnableRun(Protocol):
"""Executable unit for one scheduled run."""
@property
- def terminal_session_snapshot(self) -> CompositorSessionSnapshot | None:
+ def terminal_session_snapshot(self) -> SessionSnapshot | None:
"""Return the post-exit snapshot for the current invocation, if available."""
...
@@ -117,9 +116,7 @@ class RunScheduler:
active_tasks: dict[str, asyncio.Task[None]]
stopping: bool
runner_factory: RunRunnerFactory | None
- layer_providers: tuple[LayerProviderInput, ...]
- plugin_daemon_http_client: httpx.AsyncClient
- dify_api_http_client: httpx.AsyncClient
+ services: Services
agent_observability: AgentObservability | None
_lifecycle_lock: asyncio.Lock
@@ -127,14 +124,12 @@ class RunScheduler:
self,
*,
store: RunStore,
- plugin_daemon_http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
+ services: Services,
shutdown_grace_seconds: float = 30,
run_timeout_seconds: float = DEFAULT_AGENT_RUN_TIMEOUT_SECONDS,
stream_text_delta_coalescing_enabled: bool = True,
stream_text_delta_flush_interval_seconds: float = DEFAULT_TEXT_DELTA_FLUSH_INTERVAL_SECONDS,
stream_text_delta_max_chars: int = DEFAULT_TEXT_DELTA_MAX_CHARS,
- layer_providers: tuple[LayerProviderInput, ...] | None = None,
runner_factory: RunRunnerFactory | None = None,
agent_observability: AgentObservability | None = None,
) -> None:
@@ -146,9 +141,7 @@ class RunScheduler:
self.stream_text_delta_max_chars = stream_text_delta_max_chars
self.active_tasks = {}
self.stopping = False
- self.plugin_daemon_http_client = plugin_daemon_http_client
- self.dify_api_http_client = dify_api_http_client
- self.layer_providers = layer_providers if layer_providers is not None else create_default_layer_providers()
+ self.services = services
self.runner_factory = runner_factory
self.agent_observability = agent_observability
self._lifecycle_lock = asyncio.Lock()
@@ -316,9 +309,7 @@ class RunScheduler:
sink=self.store,
request=request,
run_id=record.run_id,
- plugin_daemon_http_client=self.plugin_daemon_http_client,
- dify_api_http_client=self.dify_api_http_client,
- layer_providers=self.layer_providers,
+ services=self.services,
is_cancelled=is_cancelled,
run_timeout_seconds=self.run_timeout_seconds,
stream_text_delta_coalescing_enabled=self.stream_text_delta_coalescing_enabled,
@@ -341,7 +332,7 @@ class RunScheduler:
self,
run_id: str,
*,
- session_snapshot: CompositorSessionSnapshot | None = None,
+ session_snapshot: SessionSnapshot | None = None,
usage: AgentRunUsage | None = None,
) -> RunFinalizationResult | None:
"""Best-effort failure event/status for shutdown-cancelled runs."""
diff --git a/dify-agent/src/dify_agent/runtime/runner.py b/dify-agent/src/dify_agent/runtime/runner.py
index 71e367d0b33..8d5527264c8 100644
--- a/dify-agent/src/dify_agent/runtime/runner.py
+++ b/dify-agent/src/dify_agent/runtime/runner.py
@@ -1,73 +1,44 @@
-"""Runtime execution for one scheduled Dify Agent run.
-
-The runner is storage-agnostic: it normalizes the public Dify composition into
-Agenton's graph/config split and executes one model run after the ``on_exit``
-policy is validated:
-
-- model runs: enter a fresh ``CompositorRun`` (or resume one from a snapshot),
- pass the current Dify system prompts as run-level instructions, run
- pydantic-ai with either the current ``run.user_prompts`` or deferred external
- tool results, emit stream events with bounded text-delta coalescing and
- agent-message annotations, apply request-level ``on_exit`` signals, and publish
- a terminal success or failure event;
-The Pydantic AI model is resolved from the active Agenton layer named by
-``DIFY_AGENT_MODEL_LAYER_ID``. An optional history layer contributes stored
-message history only through session state. Once pydantic-ai binds and builds
-messages in the run capture, every terminal outcome replaces that state with the
-captured messages after transient instructions are cleared; a failure or
-cancellation before the capture contains messages preserves the restored state.
-An interrupted run also records that its trailing response was cut short, so tool
-calls it never executed do not block the next user prompt.
-This preserves compaction rewrites and interrupted partial messages without
-saving current system prompts. An optional structured output layer named by
-``DIFY_AGENT_OUTPUT_LAYER_ID`` is read after entry and resolved into an output
-contract whose type both exposes the output schema to the model and performs
-runtime JSON Schema validation through custom Pydantic hooks. When the ask-human
-layer is active, the runtime also allows ``DeferredToolRequests`` output and
-publishes that deferred request through the normal ``run_succeeded`` event as
-``deferred_tool_call`` instead of a final ``output``. Invalid structured outputs
-or invalid deferred-tool behavior still trigger normal retries/failures before
-Dify Agent emits success. Layers still never own the FastAPI lifespan-owned
-plugin daemon or Dify API inner HTTP clients. Successful terminal events contain
-both the JSON-safe final output or deferred tool call and the session snapshot;
-there are no separate output or snapshot events to correlate.
+"""Storage-agnostic execution of native Pydantic AI module runs.
+
+Validate all JSON data and references before I/O, create fresh native components,
+and persist only State after capability cleanup. Captured history is saved in
+finally, including interrupted tool responses; current instructions are never
+stored. Live clients belong to the server lifespan and leases to native wrap_run
+scopes. Workspace and Binding retirement remain API-owned.
"""
import asyncio
from collections.abc import AsyncIterable, Callable, Mapping
-from collections import Counter
from dataclasses import dataclass
-from typing import Any, Literal, Protocol, cast, runtime_checkable
+from typing import Protocol, cast, runtime_checkable
+from types import ModuleType
-import httpx
from graphon.model_runtime.entities.llm_entities import LLMUsage
from pydantic import JsonValue, TypeAdapter
from pydantic_ai import capture_run_messages
from pydantic_ai.exceptions import ModelHTTPError, UsageLimitExceeded
from pydantic_ai.messages import AgentStreamEvent, PartDeltaEvent, PartStartEvent, TextPart, TextPartDelta
-from pydantic_ai.output import OutputSpec
-from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults
-from pydantic_ai.usage import UsageLimits
-
-from agenton.compositor import CompositorSessionSnapshot, LayerConfigInput, LayerProviderInput
-from agenton.layers.types import PydanticAITool
-from dify_agent.layers.ask_human.layer import get_ask_human_layer, validate_ask_human_layer_composition
-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer
-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer
-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer
+from pydantic_ai.usage import RunUsage, UsageLimits
+
+from dify_agent.protocol.snapshot import SessionSnapshot
+from dify_agent.runtime.context import Services
+from dify_agent.runtime.modules import REGISTRY, load_modules, create_modules, snapshot_modules
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.toolsets import AbstractToolset
+from dify_agent.layers import history as history_module
+from dify_agent.layers.prompt import layer as prompt_module
+from dify_agent.layers.dify_plugin import llm_layer as llm_module
+from dify_agent.layers.output import output_layer as output_module
+from dify_agent.layers.user_prompt import layer as user_prompt_module
+from dify_agent.layers.knowledge import layer as knowledge_module
from dify_agent.layers.knowledge.client import DifyKnowledgeBaseClientError
-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer
from dify_agent.protocol.schemas import (
AgentRunUsage,
CreateRunRequest,
DIFY_AGENT_MODEL_LAYER_ID,
- DeferredToolCallPayload,
RunFailureType,
- normalize_composition,
)
from dify_agent.runtime.agent_factory import create_agent, normalize_user_input
-from dify_agent.runtime.agenton_validation import is_agenton_enter_validation_runtime_error
-from dify_agent.runtime.compositor_factory import build_pydantic_ai_compositor, create_default_layer_providers
from dify_agent.runtime.compaction import build_compaction_capability
from dify_agent.runtime_backend import BindingLostError
from dify_agent.runtime.event_coalescer import (
@@ -83,13 +54,6 @@ from dify_agent.runtime.event_sink import (
emit_run_succeeded,
)
from dify_agent.runtime.observability import AgentObservability
-from dify_agent.runtime.history import (
- get_history_layer,
- replace_run_history,
- validate_history_layer_composition,
-)
-from dify_agent.runtime.layer_exit_signals import apply_layer_exit_signals, validate_layer_exit_signals
-from dify_agent.runtime.output_type import resolve_run_output_contract, validate_output_layer_composition
from dify_agent.runtime.user_prompt_validation import EMPTY_USER_PROMPTS_ERROR, has_non_blank_user_prompt
@@ -98,26 +62,6 @@ _MAX_AGENT_STEPS_PER_RUN = 500
DEFAULT_AGENT_RUN_TIMEOUT_SECONDS = 60 * 60
-@runtime_checkable
-class _HasUsage(Protocol):
- usage: object
-
-
-@runtime_checkable
-class _HasInputTokens(Protocol):
- input_tokens: int | None
-
-
-@runtime_checkable
-class _HasOutputTokens(Protocol):
- output_tokens: int | None
-
-
-@runtime_checkable
-class _HasTotalTokens(Protocol):
- total_tokens: int | None
-
-
@runtime_checkable
class _HasAccumulatedUsage(Protocol):
@property
@@ -159,11 +103,6 @@ def _run_failed_error_payload(exc: Exception) -> tuple[str, RunFailureType | Non
return message, None, reason
-def _has_model_layer(request: CreateRunRequest) -> bool:
- """Return whether the public composition includes the reserved model layer."""
- return any(layer.name == DIFY_AGENT_MODEL_LAYER_ID for layer in request.composition.layers)
-
-
def _extract_agent_message_delta(event: AgentStreamEvent) -> str | None:
"""Return agent-message text content from Pydantic AI stream events."""
if isinstance(event, PartDeltaEvent) and isinstance(event.delta, TextPartDelta):
@@ -177,10 +116,8 @@ def _extract_agent_message_delta(event: AgentStreamEvent) -> str | None:
class RunSuccessOutcome:
"""Normalized successful runner output before event emission."""
- result_kind: Literal["output", "deferred_tool_call"]
output: JsonValue | None
- deferred_tool_call: DeferredToolCallPayload | None
- session_snapshot: CompositorSessionSnapshot
+ session_snapshot: SessionSnapshot
usage: AgentRunUsage | None
@@ -191,16 +128,15 @@ class AgentRunRunner:
request: CreateRunRequest
run_id: str
- layer_providers: tuple[LayerProviderInput, ...]
- plugin_daemon_http_client: httpx.AsyncClient
- dify_api_http_client: httpx.AsyncClient
+ services: Services
+ registry: Mapping[str, ModuleType]
is_cancelled: Callable[[], bool]
run_timeout_seconds: float
stream_text_delta_coalescing_enabled: bool
stream_text_delta_flush_interval_seconds: float
stream_text_delta_max_chars: int
agent_observability: AgentObservability | None
- _terminal_session_snapshot: CompositorSessionSnapshot | None
+ _terminal_session_snapshot: SessionSnapshot | None
_terminal_usage: AgentRunUsage | None
def __init__(
@@ -209,9 +145,8 @@ class AgentRunRunner:
sink: RunEventSink,
request: CreateRunRequest,
run_id: str,
- plugin_daemon_http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- layer_providers: tuple[LayerProviderInput, ...] | None = None,
+ services: Services,
+ registry: Mapping[str, ModuleType] = REGISTRY,
is_cancelled: Callable[[], bool] | None = None,
run_timeout_seconds: float = DEFAULT_AGENT_RUN_TIMEOUT_SECONDS,
stream_text_delta_coalescing_enabled: bool = True,
@@ -226,9 +161,8 @@ class AgentRunRunner:
self.sink = sink
self.request = request
self.run_id = run_id
- self.plugin_daemon_http_client = plugin_daemon_http_client
- self.dify_api_http_client = dify_api_http_client
- self.layer_providers = layer_providers if layer_providers is not None else create_default_layer_providers()
+ self.services = services
+ self.registry = registry
self.is_cancelled = is_cancelled or (lambda: False)
self.run_timeout_seconds = run_timeout_seconds
self.stream_text_delta_coalescing_enabled = stream_text_delta_coalescing_enabled
@@ -239,8 +173,8 @@ class AgentRunRunner:
self._terminal_usage = None
@property
- def terminal_session_snapshot(self) -> CompositorSessionSnapshot | None:
- """Return the snapshot captured after the current compositor context exited."""
+ def terminal_session_snapshot(self) -> SessionSnapshot | None:
+ """Return the snapshot captured after native capability cleanup."""
return self._terminal_session_snapshot
@property
@@ -280,199 +214,115 @@ class AgentRunRunner:
_ = await emit_run_succeeded(
self.sink,
run_id=self.run_id,
- **(
- {"output": outcome.output}
- if outcome.result_kind == "output"
- else {"deferred_tool_call": outcome.deferred_tool_call}
- ),
+ output=outcome.output,
session_snapshot=outcome.session_snapshot,
usage=outcome.usage,
)
async def _run_agent(self) -> RunSuccessOutcome:
- """Run the normalized request through the model path.
-
- Known request-shaped Agenton enter-time failures are normalized to
- ``AgentRunValidationError``. That includes the existing small class of
- enter-time ``RuntimeError`` values reported by Agenton plus
- layer-construction or snapshot-hydration ``ValueError`` failures that
- arise before the run becomes active, such as missing shell settings for a
- requested ``dify.shell`` layer or malformed serialized shell offsets.
- Output/history-layer graph invariants are validated from the public
- composition before entering Agenton so misnamed or extra reserved layers
- never silently degrade. Later runtime failures still propagate as
- execution errors so they become terminal failed runs rather than client
- validation responses. Structured output uses a resolved contract whose
- type itself encodes both the model-facing schema and the runtime
- validation hooks, so invalid model outputs can be corrected before Dify
- Agent emits success.
- """
try:
- validate_output_layer_composition(self.request.composition)
- validate_history_layer_composition(self.request.composition)
- validate_ask_human_layer_composition(self.request.composition)
- graph_config, layer_configs = normalize_composition(self.request.composition)
- compositor = build_pydantic_ai_compositor(graph_config, providers=self.layer_providers)
- validate_layer_exit_signals(compositor, self.request.on_exit)
+ deps = load_modules(self.request, self.services, self.run_id, registry=self.registry)
+ modules = create_modules(deps, registry=self.registry)
+ model_module = modules[DIFY_AGENT_MODEL_LAYER_ID]
+ if not isinstance(model_module, llm_module.Capability):
+ raise ValueError("The llm module must provide native model assembly")
+ model = model_module.build_model(deps)
+ llm_config = llm_module.Config.model_validate(deps.layers[DIFY_AGENT_MODEL_LAYER_ID]["config"])
+ history = modules.get("history")
+ if history is not None and not isinstance(history, history_module.Capability):
+ raise ValueError("The history slot must provide the history module")
+ message_history = history.load_messages(deps) if isinstance(history, history_module.Capability) else None
+ output = modules.get("output")
+ if output is not None and not isinstance(output, output_module.Capability):
+ raise ValueError("The output slot must provide the output module")
+ output_type = (
+ output.build_output_contract(deps).output_type if isinstance(output, output_module.Capability) else str
+ )
+ user_content = []
+ for module in modules.values():
+ if isinstance(module, (prompt_module.Toolset, user_prompt_module.Capability)):
+ user_content.extend(module.build_user_content(deps))
+ eager_user_content = any(
+ isinstance(module, knowledge_module.Capability) and module.provides_user_content(deps)
+ for module in modules.values()
+ )
+ if not has_non_blank_user_prompt(user_content) and not eager_user_content:
+ raise ValueError(EMPTY_USER_PROMPTS_ERROR)
+ capabilities = [module for module in modules.values() if isinstance(module, AbstractCapability)]
+ compaction = build_compaction_capability(
+ context_window_tokens=llm_config.context_window_tokens, model_settings=llm_config.model_settings
+ )
+ if compaction is not None:
+ capabilities.append(compaction)
+ agent = create_agent(
+ model,
+ toolsets=[module for module in modules.values() if isinstance(module, AbstractToolset)],
+ capabilities=capabilities,
+ output_type=output_type,
+ )
+ if self.agent_observability is not None:
+ from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
+
+ self.agent_observability.instrument(
+ agent,
+ execution_context=DifyExecutionContextLayerConfig.model_validate(
+ deps.layers[llm_config.execution_context]["config"]
+ ),
+ )
except (KeyError, TypeError, ValueError) as exc:
raise AgentRunValidationError(str(exc)) from exc
- if not _has_model_layer(self.request):
- raise AgentRunValidationError(f"Missing required '{DIFY_AGENT_MODEL_LAYER_ID}' layer.")
- return await self._run_model(compositor=compositor, layer_configs=layer_configs)
+ async def handle_events(_ctx: object, events: AsyncIterable[AgentStreamEvent]) -> None:
+ published_events = coalesce_agent_stream_events(
+ events,
+ enabled=self.stream_text_delta_coalescing_enabled,
+ flush_interval_seconds=self.stream_text_delta_flush_interval_seconds,
+ max_chars=self.stream_text_delta_max_chars,
+ )
+ async for event in published_events:
+ if self.is_cancelled():
+ raise asyncio.CancelledError
+ await emit_pydantic_ai_event(
+ self.sink, run_id=self.run_id, data=event, agent_message_delta=_extract_agent_message_delta(event)
+ )
- async def _run_model(
- self,
- *,
- compositor: Any,
- layer_configs: dict[str, LayerConfigInput],
- ) -> RunSuccessOutcome:
- """Run the normal model/deferred-tool path inside an entered Agenton run."""
- entered_run = False
- output: JsonValue | None = None
- deferred_tool_call: DeferredToolCallPayload | None = None
- result_kind: Literal["output", "deferred_tool_call"] | None = None
- usage: AgentRunUsage | None = None
- model: Any = None
- run = None
+ timeout = asyncio.timeout(self.run_timeout_seconds)
try:
- async with compositor.enter(configs=layer_configs, session_snapshot=self.request.session_snapshot) as run:
- entered_run = True
- apply_layer_exit_signals(run, self.request.on_exit)
- user_prompts = run.user_prompts
- deferred_tool_results = _resolve_deferred_tool_results(self.request)
- if deferred_tool_results is None and not has_non_blank_user_prompt(user_prompts):
- raise AgentRunValidationError(EMPTY_USER_PROMPTS_ERROR)
-
- async def handle_events(_ctx: object, events: AsyncIterable[AgentStreamEvent]) -> None:
- published_events = coalesce_agent_stream_events(
- events,
- enabled=self.stream_text_delta_coalescing_enabled,
- flush_interval_seconds=self.stream_text_delta_flush_interval_seconds,
- max_chars=self.stream_text_delta_max_chars,
- )
- async for event in published_events:
- if self.is_cancelled():
- raise asyncio.CancelledError
- text_delta = _extract_agent_message_delta(event)
- _ = await emit_pydantic_ai_event(
- self.sink,
- run_id=self.run_id,
- data=event,
- agent_message_delta=text_delta,
- )
-
- try:
- output_contract = resolve_run_output_contract(run)
- history_layer = get_history_layer(run)
- message_history = history_layer.message_history if history_layer is not None else None
- ask_human_layer = get_ask_human_layer(run)
- llm_layer = run.get_layer(DIFY_AGENT_MODEL_LAYER_ID, DifyPluginLLMLayer)
- compaction = build_compaction_capability(
- context_window_tokens=llm_layer.config.context_window_tokens,
- model_settings=llm_layer.config.model_settings,
- )
- model = llm_layer.get_model(
- http_client=self.dify_api_http_client,
- agent_run_id=self.run_id,
- )
- tools = await _resolve_run_tools(
- run,
- plugin_daemon_http_client=self.plugin_daemon_http_client,
- dify_api_http_client=self.dify_api_http_client,
- )
- except (KeyError, TypeError, RuntimeError, ValueError) as exc:
- raise AgentRunValidationError(str(exc)) from exc
-
- if deferred_tool_results is not None and history_layer is None:
- raise AgentRunValidationError(
- "Deferred tool results require a 'history' layer with prior message history."
- )
-
- agent = create_agent(
- model,
- tools=tools,
- output_type=_resolve_agent_output_type(output_contract.output_type, ask_human_layer is not None),
- )
- if self.agent_observability is not None:
- # The model layer's required execution-context dependency is the
- # run's only carrier of Dify identity, and its node name is
- # caller-chosen, so read it through the typed dependency.
- self.agent_observability.instrument(
- agent,
- execution_context=llm_layer.deps.execution_context.config,
- )
- run_timeout = asyncio.timeout(self.run_timeout_seconds)
+ with capture_run_messages() as messages:
+ finished = False
try:
- with capture_run_messages() as captured_messages:
- agent_run_finished = False
- try:
- async with run_timeout:
- result = await agent.run(
- None if deferred_tool_results is not None else normalize_user_input(user_prompts),
- message_history=message_history,
- deferred_tool_results=deferred_tool_results,
- event_stream_handler=handle_events,
- instructions=run.prompts or None,
- capabilities=[compaction] if compaction is not None else None,
- usage_limits=UsageLimits(request_limit=_MAX_AGENT_STEPS_PER_RUN),
- )
- agent_run_finished = True
- finally:
- if captured_messages:
- replace_run_history(
- history_layer, captured_messages, interrupted=not agent_run_finished
- )
- except TimeoutError as exc:
- if not run_timeout.expired():
- raise
- raise UsageLimitExceeded(
- f"Agent run exceeded the configured limit of {self.run_timeout_seconds:g} seconds"
- ) from exc
- complete_usage = model.accumulated_usage if isinstance(model, _HasAccumulatedUsage) else None
- usage = _serialize_agent_usage(complete_usage if complete_usage is not None else _result_usage(result))
- self._terminal_usage = usage
- if isinstance(result.output, DeferredToolRequests):
- if ask_human_layer is None:
- raise AgentRunValidationError(
- "Deferred tool requests were returned, but no active ask_human layer is available for validation."
+ async with timeout:
+ result = await agent.run(
+ normalize_user_input(user_content),
+ deps=deps,
+ message_history=message_history,
+ event_stream_handler=handle_events,
+ usage_limits=UsageLimits(request_limit=_MAX_AGENT_STEPS_PER_RUN),
)
- if history_layer is None:
- raise AgentRunValidationError(
- "ask_human deferred tool requests require a 'history' layer so the pending tool call can be resumed."
- )
- deferred_tool_call = ask_human_layer.build_deferred_tool_call_payload(result.output)
- result_kind = "deferred_tool_call"
- else:
- output = _serialize_agent_output(result.output)
- result_kind = "output"
- except RuntimeError as exc:
- if not entered_run and is_agenton_enter_validation_runtime_error(exc):
- raise AgentRunValidationError(str(exc)) from exc
- raise
- except ValueError as exc:
- if not entered_run:
- raise AgentRunValidationError(str(exc)) from exc
- raise
+ finished = True
+ finally:
+ if messages and isinstance(history, history_module.Capability):
+ history.save_messages(deps, messages, interrupted=not finished)
+ complete_usage = model.accumulated_usage if isinstance(model, _HasAccumulatedUsage) else None
+ self._terminal_usage = _serialize_agent_usage(
+ complete_usage if complete_usage is not None else result.usage
+ )
+ final_output = _serialize_agent_output(result.output)
+ except TimeoutError as exc:
+ if not timeout.expired():
+ raise
+ raise UsageLimitExceeded(
+ f"Agent run exceeded the configured limit of {self.run_timeout_seconds:g} seconds"
+ ) from exc
finally:
- if entered_run and run is not None:
- self._terminal_session_snapshot = run.session_snapshot
+ # Native wrap_run scopes have exited, including cancellation cleanup.
+ self._terminal_session_snapshot = snapshot_modules(deps, registry=self.registry)
if isinstance(model, _HasAccumulatedUsage):
- accumulated_usage = _serialize_agent_usage(model.accumulated_usage)
- if accumulated_usage is not None:
- self._terminal_usage = accumulated_usage
-
- if run is None or run.session_snapshot is None:
- raise RuntimeError("Agenton run did not produce a session snapshot after exit.")
- if result_kind is None:
- raise RuntimeError("Agent run did not resolve either a final output or a deferred tool call.")
-
+ usage = _serialize_agent_usage(model.accumulated_usage)
+ if usage is not None:
+ self._terminal_usage = usage
return RunSuccessOutcome(
- result_kind=result_kind,
- output=output,
- deferred_tool_call=deferred_tool_call,
- session_snapshot=run.session_snapshot,
- usage=usage,
+ output=final_output, session_snapshot=self._terminal_session_snapshot, usage=self._terminal_usage
)
@@ -481,81 +331,17 @@ def _serialize_agent_output(output: object) -> JsonValue:
return cast(JsonValue, _AGENT_OUTPUT_ADAPTER.dump_python(output, mode="json"))
-def _result_usage(result: object) -> object | None:
- """Return pydantic-ai result usage across method/property API variants."""
- if not isinstance(result, _HasUsage):
- return None
-
- usage = result.usage
- if isinstance(usage, _HasInputTokens) or isinstance(usage, _HasOutputTokens):
- return usage
- if callable(usage):
- usage_getter = cast(Callable[[], object], usage)
- return usage_getter()
- return usage
-
-
-def _serialize_agent_usage(usage: object | None) -> AgentRunUsage | None:
+def _serialize_agent_usage(usage: LLMUsage | RunUsage | None) -> AgentRunUsage | None:
"""Convert complete daemon or fallback pydantic-ai usage into the public shape."""
if usage is None:
return None
if isinstance(usage, LLMUsage):
return AgentRunUsage.model_validate(usage.model_dump(mode="python"))
- input_tokens = int(usage.input_tokens or 0) if isinstance(usage, _HasInputTokens) else 0
- output_tokens = int(usage.output_tokens or 0) if isinstance(usage, _HasOutputTokens) else 0
- total_tokens = int(usage.total_tokens or 0) if isinstance(usage, _HasTotalTokens) else 0
return AgentRunUsage(
- prompt_tokens=input_tokens,
- completion_tokens=output_tokens,
- total_tokens=total_tokens,
+ prompt_tokens=usage.input_tokens,
+ completion_tokens=usage.output_tokens,
+ total_tokens=usage.total_tokens,
)
-def _resolve_agent_output_type(output_type: OutputSpec[object], allow_deferred_tools: bool) -> OutputSpec[object]:
- """Return the run output type, optionally augmented with deferred-tool support."""
- if not allow_deferred_tools:
- return output_type
- return cast(OutputSpec[object], [output_type, DeferredToolRequests])
-
-
-def _resolve_deferred_tool_results(request: CreateRunRequest) -> DeferredToolResults | None:
- """Convert public deferred tool results into the pydantic-ai resume input."""
- if request.deferred_tool_results is None:
- return None
- return request.deferred_tool_results.to_pydantic_ai()
-
-
-async def _resolve_run_tools(
- run: Any,
- *,
- plugin_daemon_http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
-) -> list[PydanticAITool[object]]:
- """Return the static compositor tools plus any Dify runtime tools."""
- resolved_tools = list(cast(list[PydanticAITool[object]], run.tools))
- for slot in run.slots.values():
- layer = slot.layer
- if isinstance(layer, DifyPluginToolsLayer):
- resolved_tools.extend(
- await layer.get_tools(
- http_client=plugin_daemon_http_client,
- dify_api_http_client=dify_api_http_client,
- )
- )
- if isinstance(layer, DifyCoreToolsLayer):
- resolved_tools.extend(await layer.get_tools(http_client=dify_api_http_client))
- if isinstance(layer, DifyKnowledgeBaseLayer):
- resolved_tools.extend(await layer.get_tools(http_client=dify_api_http_client))
- _validate_unique_tool_names(resolved_tools)
- return resolved_tools
-
-
-def _validate_unique_tool_names(tools: list[PydanticAITool[object]]) -> None:
- """Reject duplicate tool names across static and dynamic tool sources."""
- duplicate_names = sorted(name for name, count in Counter(tool.name for tool in tools).items() if count > 1)
- if duplicate_names:
- names = ", ".join(duplicate_names)
- raise ValueError(f"Agent run requires unique tool names across all layers, got duplicates: {names}.")
-
-
__all__ = ["AgentRunRunner", "AgentRunValidationError"]
diff --git a/dify-agent/src/dify_agent/runtime/user_prompt_validation.py b/dify-agent/src/dify_agent/runtime/user_prompt_validation.py
index c2cda83accc..b0287d34cd0 100644
--- a/dify-agent/src/dify_agent/runtime/user_prompt_validation.py
+++ b/dify-agent/src/dify_agent/runtime/user_prompt_validation.py
@@ -1,7 +1,7 @@
-"""Validation for effective user prompts produced by Agenton runs.
+"""Validation for effective user input assembled from module configuration.
-Validation happens after safe compositor construction and run entry so runtime
-execution uses the same transformed prompts as the actual pydantic-ai input.
+The runner validates assembled current prompt content before resource acquisition.
+Knowledge user-query retrieval can also provide input through its native hook.
Blank string fragments do not count as meaningful input; non-string
``UserContent`` is treated as intentional content because rich media/message
parts do not have a universal whitespace representation.
diff --git a/dify-agent/src/dify_agent/runtime_backend/e2b.py b/dify-agent/src/dify_agent/runtime_backend/e2b.py
index 7f09cb5a9f3..398dd0e2f1e 100644
--- a/dify-agent/src/dify_agent/runtime_backend/e2b.py
+++ b/dify-agent/src/dify_agent/runtime_backend/e2b.py
@@ -3,7 +3,7 @@
Dify API persists only opaque Home Snapshot, Binding, and Workspace backend
refs. This adapter maps those refs to E2B resources internally. API keys,
traffic tokens, SDK objects, shellctl clients, and ``RuntimeLease`` objects stay
-operation-local and are never serialized into Agenton state.
+operation-local and are never serialized into module JSON state.
"""
from __future__ import annotations
diff --git a/dify-agent/src/dify_agent/server/app.py b/dify-agent/src/dify_agent/server/app.py
index 36219c9c6e5..abae36a5e0a 100644
--- a/dify-agent/src/dify_agent/server/app.py
+++ b/dify-agent/src/dify_agent/server/app.py
@@ -7,10 +7,8 @@ rather than request handlers, so client disconnects do not cancel the agent
runtime. Redis persists run records and per-run event streams with configured
retention. Optional provider accounting is exposed as a separate one-shot HTTP
endpoint driven by Celery Beat; it starts no tasks during lifespan startup and
-adds no reporting to business operations. Redis is not used as a run job queue. Agenton layers and providers
-stay state-only: they borrow the lifespan-owned clients through the runner and
-receive runtime-backend and Shell settings through provider construction rather
-than reading environment variables themselves. The standard server mounts the
+adds no reporting to business operations. Redis is not used as a run job queue. Modules borrow lifespan-owned services through run dependencies; their JSON
+configuration and state never retain live infrastructure. The standard server mounts the
HTTP Agent Stub router. Process-level platform Logfire instrumentation is
configured at app construction time. Logfire-platform export is token-gated;
standard OTLP export follows the SDK environment configuration, including
@@ -29,7 +27,7 @@ from redis.asyncio import Redis
from dify_agent.agent_stub.shell_env import ShellAgentStubTokenFactory
from dify_agent.agent_stub.server.router import create_agent_stub_router
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
+from dify_agent.runtime.context import Services
from dify_agent.runtime.run_scheduler import RunScheduler
from dify_agent.server.auth import create_bearer_token_dependency
from dify_agent.server.observability import configure_agent_observability, configure_server_observability
@@ -67,16 +65,6 @@ def create_app(settings: ServerSettings | None = None) -> FastAPI:
agent_stub_file_request_handler = resolved_settings.create_agent_stub_file_request_handler()
agent_stub_config_request_handler = resolved_settings.create_agent_stub_config_request_handler()
runtime_backend_profile = resolved_settings.build_runtime_backend_profile()
- layer_providers = create_default_layer_providers(
- plugin_daemon_url=resolved_settings.plugin_daemon_url,
- plugin_daemon_api_key=resolved_settings.plugin_daemon_api_key,
- inner_api_url=resolved_settings.inner_api_url,
- inner_api_key=resolved_settings.inner_api_key or "",
- runtime_backend_profile=runtime_backend_profile,
- shell_redact_patterns=resolved_settings.get_shell_redact_patterns(),
- agent_stub_api_base_url=resolved_settings.agent_stub_api_base_url,
- agent_stub_token_factory=agent_stub_token_factory,
- )
binding_file_service = (
BindingFileService(
execution_bindings=runtime_backend_profile.execution_bindings,
@@ -117,14 +105,23 @@ def create_app(settings: ServerSettings | None = None) -> FastAPI:
)
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=plugin_daemon_http_client,
- dify_api_http_client=dify_api_inner_http_client,
+ services=Services(
+ plugin_daemon_http_client=plugin_daemon_http_client,
+ dify_api_http_client=dify_api_inner_http_client,
+ plugin_daemon_url=resolved_settings.plugin_daemon_url,
+ plugin_daemon_api_key=resolved_settings.plugin_daemon_api_key,
+ inner_api_url=resolved_settings.inner_api_url,
+ inner_api_key=resolved_settings.inner_api_key or "",
+ runtime_backend_profile=runtime_backend_profile,
+ shell_redact_patterns=resolved_settings.get_shell_redact_patterns(),
+ agent_stub_api_base_url=resolved_settings.agent_stub_api_base_url,
+ agent_stub_token_factory=agent_stub_token_factory,
+ ),
shutdown_grace_seconds=resolved_settings.shutdown_grace_seconds,
run_timeout_seconds=resolved_settings.run_timeout_seconds,
stream_text_delta_coalescing_enabled=resolved_settings.stream_text_delta_coalescing_enabled,
stream_text_delta_flush_interval_seconds=(resolved_settings.stream_text_delta_flush_interval_ms / 1000),
stream_text_delta_max_chars=resolved_settings.stream_text_delta_max_chars,
- layer_providers=layer_providers,
agent_observability=agent_observability,
)
state["store"] = store
diff --git a/dify-agent/src/dify_agent/server/settings.py b/dify-agent/src/dify_agent/server/settings.py
index 207e14b7675..a5b5623a9ba 100644
--- a/dify-agent/src/dify_agent/server/settings.py
+++ b/dify-agent/src/dify_agent/server/settings.py
@@ -2,7 +2,7 @@
Outbound HTTP client settings describe the FastAPI lifespan-owned
``httpx.AsyncClient`` instances shared by local run tasks for plugin-daemon and
-Dify API inner calls. Layers and Agenton providers do not own those clients, so
+Dify API inner calls. Native modules borrow those clients, so
these settings are process resource limits rather than per-run lifecycle knobs.
Endpoint URLs and API keys stay service-specific. The Agent Stub also uses this
settings model directly: the public Agent Stub API base URL, server secret,
@@ -12,7 +12,7 @@ and optional Dify inner API bridge settings live here under the
import httpx
-from typing import ClassVar, Literal, cast
+from typing import ClassVar, Literal, cast, override
from pydantic import AliasChoices, AnyHttpUrl, Field, SecretStr, TypeAdapter, field_validator, model_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -158,6 +158,7 @@ class ServerSettings(BaseSettings):
)
@classmethod
+ @override
def settings_customise_sources(
cls,
settings_cls: type[BaseSettings],
diff --git a/dify-agent/src/dify_agent/storage/redis_run_store.py b/dify-agent/src/dify_agent/storage/redis_run_store.py
index a2a61cd9231..98a4fa78257 100644
--- a/dify-agent/src/dify_agent/storage/redis_run_store.py
+++ b/dify-agent/src/dify_agent/storage/redis_run_store.py
@@ -10,11 +10,11 @@ sensitive runtime configuration.
"""
from collections.abc import AsyncIterator, Awaitable
-from typing import cast
+from typing import cast, override
from redis.asyncio import Redis
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.protocol.schemas import (
AgentRunUsage,
RUN_EVENT_ADAPTER,
@@ -198,6 +198,7 @@ class RedisRunStore(RunEventSink):
value = value.decode()
return RunRecord.model_validate_json(value)
+ @override
async def append_event(self, event: NonTerminalRunEvent) -> str:
"""Append a non-terminal event JSON payload with refreshed TTLs."""
events_key = run_events_key(self.prefix, event.run_id)
@@ -215,6 +216,7 @@ class RedisRunStore(RunEventSink):
event_id = results[0]
return event_id.decode() if isinstance(event_id, bytes) else str(event_id)
+ @override
async def finalize_run(self, event: TerminalRunEvent) -> RunFinalizationResult:
"""Atomically append the first success/failure event and update its run record."""
status, error, error_type = terminal_event_status_fields(event)
@@ -297,7 +299,7 @@ class RedisRunStore(RunEventSink):
run_id: str,
intent: RunCancellationIntent,
*,
- session_snapshot: CompositorSessionSnapshot | None = None,
+ session_snapshot: SessionSnapshot | None = None,
usage: AgentRunUsage | None = None,
) -> RunFinalizationResult:
"""Atomically publish cancellation after the owner runner has exited."""
diff --git a/dify-agent/tests/docs/test_examples.py b/dify-agent/tests/docs/test_examples.py
index 83280724b2d..253fb8e419a 100644
--- a/dify-agent/tests/docs/test_examples.py
+++ b/dify-agent/tests/docs/test_examples.py
@@ -26,7 +26,6 @@ def find_doc_examples() -> Iterable[ParameterSet]:
for example in find_examples(
root_dir / "docs",
root_dir / "src",
- root_dir / "examples" / "agenton",
root_dir / "examples" / "dify_agent",
):
path = example.path.relative_to(root_dir)
@@ -47,7 +46,7 @@ def test_documentation_examples(example: CodeExample, eval_example: EvalExample)
isort=True,
upgrade=True,
quotes="double",
- known_first_party=["agenton", "agenton_collections", "dify_agent"],
+ known_first_party=["dify_agent"],
)
if not opt_lint.startswith("skip"):
diff --git a/dify-agent/tests/docs/test_snippets.py b/dify-agent/tests/docs/test_snippets.py
index 89428323d08..9086cd50b92 100644
--- a/dify-agent/tests/docs/test_snippets.py
+++ b/dify-agent/tests/docs/test_snippets.py
@@ -38,9 +38,9 @@ if __name__ == "__main__":
parsed = parse_file_sections(source)
assert "main" in parsed.sections
- markdown = '```snippet {path="/examples/agenton/agenton_examples/session_snapshot.py"}\n```'
+ markdown = '```snippet {path="/examples/dify_agent/dify_agent_examples/run_server_consumer.py"}\n```'
rendered = inject_snippets(markdown, PROJECT_ROOT / "docs")
- assert rendered.startswith('```py {title="examples/agenton/agenton_examples/session_snapshot.py"}')
+ assert rendered.startswith('```py {title="examples/dify_agent/dify_agent_examples/run_server_consumer.py"}')
assert "async def main() -> None:" in rendered
assert "asyncio.run(main())" in rendered
diff --git a/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py b/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py
index 5bf579bee03..1b1791adfca 100644
--- a/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py
+++ b/dify-agent/tests/integration/dify_agent/storage/test_terminal_finalization.py
@@ -12,7 +12,7 @@ import httpx
import pytest
from redis.asyncio import Redis
-from agenton.compositor import CompositorSessionSnapshot
+from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.protocol.schemas import (
CancelRunRequest,
CreateRunRequest,
@@ -25,6 +25,7 @@ from dify_agent.protocol.schemas import (
RunSucceededEventData,
utc_now,
)
+from dify_agent.runtime.context import Services
from dify_agent.runtime.cancellation import RunCancellationIntent
from dify_agent.runtime.run_scheduler import RunScheduler
from dify_agent.storage.redis_keys import run_cancel_intent_key, run_events_key, run_record_key
@@ -40,7 +41,7 @@ def _success_or_failure_event(kind: str, run_id: str) -> RunSucceededEvent | Run
run_id=run_id,
data=RunSucceededEventData(
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
return RunFailedEvent(run_id=run_id, data=RunFailedEventData(error="model failed"))
@@ -108,7 +109,7 @@ def test_success_and_cancel_intent_commit_exactly_one_matching_terminal(redis_ur
run_id=record.run_id,
data=RunSucceededEventData(
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
@@ -175,7 +176,7 @@ def test_event_stream_is_trimmed_and_keeps_the_terminal_event(redis_url: str) ->
run_id=record.run_id,
data=RunSucceededEventData(
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
)
@@ -263,7 +264,7 @@ def test_cancellation_intent_lifecycle_and_terminal_exclusion(redis_url: str) ->
first_finalization = await store.finalize_cancellation(
record.run_id,
intent,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
)
repeated_finalization = await store.finalize_cancellation(record.run_id, intent)
post_terminal_status = await store.request_cancellation(
@@ -369,17 +370,12 @@ def test_non_owner_scheduler_cancellation_stops_owner_runner(redis_url: str) ->
async with httpx.AsyncClient() as http_client:
owner_scheduler = RunScheduler(
store=owner_store,
- plugin_daemon_http_client=http_client,
- dify_api_http_client=http_client,
- runner_factory=lambda _record, _request: BlockingRunner(
- started=runner_started,
- stopped=runner_stopped,
- ),
+ runner_factory=lambda _record, _request: BlockingRunner(started=runner_started, stopped=runner_stopped),
+ services=Services(plugin_daemon_http_client=http_client, dify_api_http_client=http_client),
)
remote_scheduler = RunScheduler(
store=remote_store,
- plugin_daemon_http_client=http_client,
- dify_api_http_client=http_client,
+ services=Services(plugin_daemon_http_client=http_client, dify_api_http_client=http_client),
)
try:
record = await owner_scheduler.create_run(CreateRunRequest(composition=RunComposition(layers=[])))
diff --git a/dify-agent/tests/local/agenton/__init__.py b/dify-agent/tests/local/agenton/__init__.py
deleted file mode 100644
index 8b137891791..00000000000
--- a/dify-agent/tests/local/agenton/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/dify-agent/tests/local/agenton/compositor/__init__.py b/dify-agent/tests/local/agenton/compositor/__init__.py
deleted file mode 100644
index 8b137891791..00000000000
--- a/dify-agent/tests/local/agenton/compositor/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/dify-agent/tests/local/agenton/compositor/test_builder_snapshot.py b/dify-agent/tests/local/agenton/compositor/test_builder_snapshot.py
deleted file mode 100644
index b43b0d1e71f..00000000000
--- a/dify-agent/tests/local/agenton/compositor/test_builder_snapshot.py
+++ /dev/null
@@ -1,337 +0,0 @@
-import asyncio
-from dataclasses import dataclass
-
-import pytest
-from pydantic import BaseModel, ConfigDict, ValidationError
-from typing_extensions import override
-
-import agenton.compositor as compositor_module
-import agenton.layers as layers_module
-from agenton.compositor import (
- Compositor,
- LayerConfigInput,
- LayerNode,
- LayerNodeConfig,
- LayerProvider,
- LayerProviderInput,
-)
-from agenton.layers import EmptyLayerConfig, Layer, LayerDeps, NoLayerDeps, PlainLayer
-from agenton_collections.layers.plain import ObjectLayer, PromptLayer, PromptLayerConfig
-
-
-EXPECTED_FACADE_EXPORTS = [
- "Compositor",
- "CompositorConfig",
- "CompositorConfigValue",
- "CompositorRun",
- "CompositorSessionSnapshot",
- "CompositorSessionSnapshotValue",
- "CompositorTransformer",
- "CompositorTransformerKwargs",
- "LayerFactory",
- "LayerNode",
- "LayerNodeConfig",
- "LayerProvider",
- "LayerRunSlot",
- "LayerSessionSnapshot",
-]
-
-EXPECTED_DIRECT_IMPORT_COMPAT_NAMES = ["LayerConfigInput", "LayerProviderInput"]
-
-
-@dataclass(slots=True)
-class InstanceOnlyLayer(PlainLayer[NoLayerDeps]):
- pass
-
-
-@dataclass(slots=True)
-class RequiredConstructorLayer(PlainLayer[NoLayerDeps]):
- value: str
-
-
-def test_layer_provider_from_layer_type_uses_declared_schema_and_type_id() -> None:
- provider = LayerProvider.from_layer_type(PromptLayer)
-
- assert provider.type_id == "plain.prompt"
- assert provider.layer_type is PromptLayer
-
- layer = provider.create_layer(PromptLayerConfig(prefix="hello", user="ask politely"))
-
- assert isinstance(layer, PromptLayer)
- assert layer.config == PromptLayerConfig(prefix="hello", user="ask politely")
- assert layer.prefix_prompts == ["hello"]
-
- with pytest.raises(TypeError, match="cannot be created from empty config"):
- LayerProvider.from_layer_type(RequiredConstructorLayer).create_layer()
-
-
-def test_compositor_from_config_uses_providers_and_enter_configs_by_node_name() -> None:
- compositor = Compositor.from_config(
- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},
- providers=[PromptLayer],
- )
-
- async def run() -> None:
- async with compositor.enter(
- configs={"prompt": {"prefix": "hello", "user": "ask politely", "suffix": ["bye"]}}
- ) as active_run:
- assert [prompt.value for prompt in active_run.prompts] == ["hello", "bye"]
- assert [prompt.value for prompt in active_run.user_prompts] == ["ask politely"]
-
- asyncio.run(run())
-
- with pytest.raises(ValidationError):
- asyncio.run(_enter_once(compositor, configs={"prompt": {"unknown": "field"}}))
-
-
-def test_layer_node_config_has_no_runtime_state_or_layer_config() -> None:
- node = LayerNodeConfig(
- name="prompt",
- type="plain.prompt",
- deps={"source": "other"},
- metadata={"label": "Prompt"},
- )
-
- assert node.model_dump(mode="json") == {
- "name": "prompt",
- "type": "plain.prompt",
- "deps": {"source": "other"},
- "metadata": {"label": "Prompt"},
- }
- assert "runtime_state" not in LayerNodeConfig.model_fields
- assert "config" not in LayerNodeConfig.model_fields
-
-
-def test_node_providers_override_type_id_providers_for_serializable_graphs() -> None:
- override_provider = LayerProvider.from_factory(
- layer_type=PromptLayer,
- create=lambda config: PromptLayer(prefix="override"),
- )
- compositor = Compositor.from_config(
- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},
- providers=[PromptLayer],
- node_providers={"prompt": override_provider},
- )
-
- async def run() -> None:
- async with compositor.enter(configs={"prompt": {"prefix": "ignored"}}) as active_run:
- assert [prompt.value for prompt in active_run.prompts] == ["override"]
-
- asyncio.run(run())
-
-
-def test_from_config_rejects_missing_duplicate_and_unknown_providers() -> None:
- with pytest.raises(KeyError, match="Layer type id 'missing' is not registered"):
- Compositor.from_config({"layers": [{"name": "node", "type": "missing"}]}, providers=[])
-
- with pytest.raises(ValueError, match="already registered"):
- Compositor.from_config(
- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},
- providers=[PromptLayer, PromptLayer],
- )
-
- with pytest.raises(ValueError, match="must declare a type_id"):
- Compositor.from_config(
- {"layers": [{"name": "node", "type": "instance.only"}]},
- providers=[InstanceOnlyLayer],
- )
-
- with pytest.raises(ValueError, match="unknown layer node names: other"):
- Compositor.from_config(
- {"layers": [{"name": "prompt", "type": "plain.prompt"}]},
- providers=[PromptLayer],
- node_providers={"other": PromptLayer},
- )
-
-
-def test_compositor_run_get_layer_returns_named_layer_and_validates_type() -> None:
- compositor = Compositor([LayerNode("obj", _object_provider("value"))])
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- layer = active_run.get_layer("obj", ObjectLayer)
- assert active_run.get_layer("obj") is layer
- assert layer.value == "value"
-
- with pytest.raises(KeyError, match="Layer 'missing' is not defined"):
- active_run.get_layer("missing")
-
- with pytest.raises(TypeError, match="Layer 'obj' must be PromptLayer, got ObjectLayer"):
- active_run.get_layer("obj", PromptLayer)
-
- asyncio.run(run())
-
-
-class ObjectConsumerDeps(LayerDeps):
- obj: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass(slots=True)
-class ObjectConsumerLayer(PlainLayer[ObjectConsumerDeps]):
- @property
- @override
- def prefix_prompts(self) -> list[str]:
- return [self.deps.obj.value]
-
-
-def test_python_native_construction_mixes_layer_classes_and_providers() -> None:
- compositor = Compositor(
- [
- LayerNode("prompt", PromptLayer),
- LayerNode("obj", _object_provider("instance")),
- LayerNode("consumer", ObjectConsumerLayer, deps={"obj": "obj"}),
- ]
- )
-
- async def run() -> None:
- async with compositor.enter(configs={"prompt": {"prefix": "cfg"}}) as active_run:
- assert [prompt.value for prompt in active_run.prompts] == ["cfg", "instance"]
-
- asyncio.run(run())
-
-
-class SerializableState(BaseModel):
- resource_id: str = ""
- created: bool = False
- resumed: bool = False
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-@dataclass(slots=True)
-class StateLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, SerializableState]):
- created_hooks: int = 0
- resumed_hooks: int = 0
-
- @override
- async def on_context_create(self) -> None:
- self.created_hooks += 1
- self.runtime_state.created = True
-
- @override
- async def on_context_resume(self) -> None:
- self.resumed_hooks += 1
- self.runtime_state.resumed = True
-
-
-def test_snapshot_contains_runtime_state_only_not_config_deps_or_resources() -> None:
- compositor = Compositor([LayerNode("state", StateLayer)])
-
- async def get_snapshot() -> dict[str, object]:
- async with compositor.enter() as active_run:
- state_layer = active_run.get_layer("state", StateLayer)
- state_layer.runtime_state.resource_id = "abc"
- assert active_run.session_snapshot is not None
- return active_run.session_snapshot.model_dump(mode="json")
-
- dumped = asyncio.run(get_snapshot())
- assert dumped == {
- "schema_version": 1,
- "layers": [
- {
- "name": "state",
- "lifecycle_state": "closed",
- "runtime_state": {"resource_id": "abc", "created": True, "resumed": False},
- }
- ],
- }
-
-
-def test_hydrate_validates_runtime_state_and_resume_mutates_layer_self() -> None:
- compositor = Compositor([LayerNode("state", StateLayer)])
-
- bad_snapshot = {"layers": [{"name": "state", "lifecycle_state": "suspended", "runtime_state": {"wrong": "field"}}]}
- with pytest.raises(ValidationError):
- asyncio.run(_enter_once(compositor, session_snapshot=bad_snapshot))
-
- good_snapshot = {
- "layers": [
- {
- "name": "state",
- "lifecycle_state": "suspended",
- "runtime_state": {"resource_id": "abc", "created": True, "resumed": False},
- }
- ]
- }
-
- async def run() -> None:
- async with compositor.enter(session_snapshot=good_snapshot) as active_run:
- layer = active_run.get_layer("state", StateLayer)
- assert layer.runtime_state.resource_id == "abc"
- assert layer.runtime_state.resumed is True
- assert layer.resumed_hooks == 1
-
- asyncio.run(run())
-
-
-def test_hydrate_rejects_mismatched_snapshot_layer_names() -> None:
- compositor = Compositor([LayerNode("state", StateLayer)])
-
- with pytest.raises(ValueError, match=r"Expected \[state\], got \[other\]"):
- asyncio.run(
- _enter_once(
- compositor,
- session_snapshot={"layers": [{"name": "other", "lifecycle_state": "new", "runtime_state": {}}]},
- )
- )
-
-
-def test_removed_lifecycle_and_resource_apis_are_not_public_exports() -> None:
- assert not hasattr(compositor_module, "CompositorBuilder")
- assert not hasattr(compositor_module, "LayerRegistry")
- assert not hasattr(compositor_module, "LayerDescriptor")
- assert not hasattr(layers_module, "LayerControl")
- assert not hasattr(layers_module, "EmptyRuntimeHandles")
- assert not hasattr(Layer, "enter")
- assert not hasattr(Layer, "hydrate_session_state")
- assert not hasattr(Layer, "suspend_on_exit")
- assert not hasattr(Layer, "delete_on_exit")
- assert not hasattr(Layer, "runtime_handles")
- assert not hasattr(Layer, "require_control")
- assert not hasattr(Layer, "control_for")
- assert not hasattr(Layer, "enter_async_resource")
- assert not hasattr(Layer, "add_async_cleanup")
-
-
-def test_facade_keeps_direct_import_type_aliases_without_expanding___all__() -> None:
- assert compositor_module.LayerConfigInput is LayerConfigInput
- assert compositor_module.LayerProviderInput is LayerProviderInput
- assert LayerConfigInput.__module__ == "agenton.compositor"
- assert LayerProviderInput.__module__ == "agenton.compositor"
- assert LayerConfigInput.__name__ == "LayerConfigInput"
- assert LayerProviderInput.__name__ == "LayerProviderInput"
- assert "LayerConfigInput" not in compositor_module.__all__
- assert "LayerProviderInput" not in compositor_module.__all__
-
-
-def test_facade_export_surface_matches_split_contract() -> None:
- compatibility_names = [*EXPECTED_FACADE_EXPORTS, *EXPECTED_DIRECT_IMPORT_COMPAT_NAMES]
-
- assert compositor_module.__all__ == EXPECTED_FACADE_EXPORTS
-
- namespace: dict[str, object] = {}
- exec(
- "from agenton.compositor import " + ", ".join(compatibility_names),
- {},
- namespace,
- )
-
- for name in compatibility_names:
- assert namespace[name] is getattr(compositor_module, name)
-
-
-def _object_provider(value: str) -> LayerProvider[ObjectLayer[str]]:
- return LayerProvider.from_factory(layer_type=ObjectLayer, create=lambda config: ObjectLayer(value))
-
-
-async def _enter_once(
- compositor: Compositor,
- *,
- configs: dict[str, object] | None = None,
- session_snapshot: object | None = None,
-) -> None:
- async with compositor.enter(
- configs=configs, # pyright: ignore[reportArgumentType]
- session_snapshot=session_snapshot, # pyright: ignore[reportArgumentType]
- ):
- pass
diff --git a/dify-agent/tests/local/agenton/compositor/test_direct_deps.py b/dify-agent/tests/local/agenton/compositor/test_direct_deps.py
deleted file mode 100644
index b7ae26ec5cf..00000000000
--- a/dify-agent/tests/local/agenton/compositor/test_direct_deps.py
+++ /dev/null
@@ -1,138 +0,0 @@
-import asyncio
-from dataclasses import dataclass
-
-import pytest
-from typing_extensions import override
-
-from agenton.compositor import Compositor, LayerNode, LayerProvider
-from agenton.layers import EmptyLayerConfig, LayerDeps, PlainLayer
-from agenton_collections.layers.plain import ObjectLayer
-
-
-class RenamedObjectDeps(LayerDeps):
- renamed: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass(slots=True)
-class RenamedConsumerLayer(PlainLayer[RenamedObjectDeps]):
- @property
- @override
- def prefix_prompts(self) -> list[str]:
- return [self.deps.renamed.value]
-
-
-class SameNameObjectDeps(LayerDeps):
- same: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass(slots=True)
-class SameNameConsumerLayer(PlainLayer[SameNameObjectDeps]):
- @property
- @override
- def prefix_prompts(self) -> list[str]:
- return [self.deps.same.value]
-
-
-class OptionalObjectDeps(LayerDeps):
- maybe: ObjectLayer[str] | None # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass(slots=True)
-class OptionalConsumerLayer(PlainLayer[OptionalObjectDeps]):
- pass
-
-
-def _object_provider(value: str) -> LayerProvider[ObjectLayer[str]]:
- return LayerProvider.from_factory(
- layer_type=ObjectLayer,
- create=lambda config: ObjectLayer(value),
- )
-
-
-def test_direct_deps_access_uses_explicit_dependency_rename() -> None:
- compositor = Compositor(
- [
- LayerNode("actual", _object_provider("target")),
- LayerNode("consumer", RenamedConsumerLayer, deps={"renamed": "actual"}),
- ]
- )
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- target = active_run.get_layer("actual", ObjectLayer)
- consumer = active_run.get_layer("consumer", RenamedConsumerLayer)
- assert consumer.deps.renamed is target
- assert [prompt.value for prompt in active_run.prompts] == ["target"]
-
- asyncio.run(run())
-
-
-def test_direct_deps_access_uses_explicit_same_name_dependency() -> None:
- compositor = Compositor(
- [
- LayerNode("same", _object_provider("target")),
- LayerNode("consumer", SameNameConsumerLayer, deps={"same": "same"}),
- ]
- )
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- target = active_run.get_layer("same", ObjectLayer)
- consumer = active_run.get_layer("consumer", SameNameConsumerLayer)
- assert consumer.deps.same is target
- assert [prompt.value for prompt in active_run.prompts] == ["target"]
-
- asyncio.run(run())
-
-
-def test_optional_missing_dependency_is_bound_to_none() -> None:
- compositor = Compositor([LayerNode("consumer", OptionalConsumerLayer)])
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- consumer = active_run.get_layer("consumer", OptionalConsumerLayer)
- assert consumer.deps.maybe is None
-
- asyncio.run(run())
-
-
-def test_missing_required_dependency_is_rejected_before_hooks() -> None:
- compositor = Compositor([LayerNode("consumer", SameNameConsumerLayer)])
-
- with pytest.raises(ValueError, match="Dependency 'same' is required"):
- asyncio.run(_enter_once(compositor))
-
-
-def test_unknown_dependency_mapping_is_rejected_for_compositor_construction() -> None:
- with pytest.raises(ValueError, match="unknown dependency keys: missing"):
- Compositor([LayerNode("consumer", RenamedConsumerLayer, deps={"missing": "target"})])
-
-
-def test_undefined_dependency_target_is_rejected_for_compositor_construction() -> None:
- with pytest.raises(ValueError, match="depends on undefined layer names: missing_target"):
- Compositor([LayerNode("consumer", RenamedConsumerLayer, deps={"renamed": "missing_target"})])
-
-
-def test_dependency_target_must_precede_dependent_layer_in_graph_order() -> None:
- with pytest.raises(ValueError, match="must target preceding layer nodes"):
- Compositor(
- [
- LayerNode("consumer", RenamedConsumerLayer, deps={"renamed": "target"}),
- LayerNode("target", _object_provider("value")),
- ]
- )
-
-
-def test_duplicate_layer_node_name_is_rejected() -> None:
- with pytest.raises(ValueError, match="Duplicate layer name 'same'"):
- Compositor(
- [
- LayerNode("same", _object_provider("first")),
- LayerNode("same", _object_provider("second")),
- ]
- )
-
-
-async def _enter_once(compositor: Compositor) -> None:
- async with compositor.enter(configs={"consumer": EmptyLayerConfig()}):
- pass
diff --git a/dify-agent/tests/local/agenton/compositor/test_enter.py b/dify-agent/tests/local/agenton/compositor/test_enter.py
deleted file mode 100644
index d22b91a94a6..00000000000
--- a/dify-agent/tests/local/agenton/compositor/test_enter.py
+++ /dev/null
@@ -1,982 +0,0 @@
-import asyncio
-from collections.abc import AsyncGenerator, Iterator
-from contextlib import asynccontextmanager
-from dataclasses import dataclass, field
-from itertools import count
-
-import pytest
-from pydantic import BaseModel, ConfigDict, ValidationError
-from typing_extensions import override
-
-from agenton.compositor import Compositor, CompositorSessionSnapshot, LayerNode, LayerProvider
-from agenton.layers import (
- EmptyLayerConfig,
- ExitIntent,
- LayerConfig,
- LifecycleState,
- NoLayerDeps,
- PlainLayer,
-)
-
-
-@dataclass(slots=True)
-class TraceLayer(PlainLayer[NoLayerDeps]):
- """Layer that records no-arg lifecycle events observable to tests."""
-
- events: list[str] = field(default_factory=list)
-
- @override
- async def on_context_create(self) -> None:
- self.events.append("create")
-
- @override
- async def on_context_suspend(self) -> None:
- self.events.append("suspend")
-
- @override
- async def on_context_resume(self) -> None:
- self.events.append("resume")
-
- @override
- async def on_context_delete(self) -> None:
- self.events.append("delete")
-
-
-def _compositor(*layer_names: str) -> Compositor:
- return Compositor([LayerNode(layer_name, TraceLayer) for layer_name in layer_names])
-
-
-def test_same_compositor_enters_multiple_times_with_fresh_layers_and_snapshot_resume() -> None:
- compositor = _compositor("first", "second")
- runs = []
-
- async def run() -> None:
- async with compositor.enter() as first_run:
- assert [slot.lifecycle_state for slot in first_run.slots.values()] == [
- LifecycleState.ACTIVE,
- LifecycleState.ACTIVE,
- ]
- first_run.suspend_on_exit()
- assert [slot.exit_intent for slot in first_run.slots.values()] == [
- ExitIntent.SUSPEND,
- ExitIntent.SUSPEND,
- ]
- runs.append(first_run)
-
- assert first_run.session_snapshot is not None
- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:
- assert resumed_run.get_layer("first", TraceLayer).events == ["resume"]
- assert resumed_run.get_layer("second", TraceLayer).events == ["resume"]
- runs.append(resumed_run)
-
- asyncio.run(run())
-
- first_layer = runs[0].get_layer("first", TraceLayer)
- resumed_layer = runs[1].get_layer("first", TraceLayer)
- assert first_layer is not resumed_layer
- assert first_layer.events == ["create", "suspend"]
- assert resumed_layer.events == ["resume", "delete"]
- assert runs[1].session_snapshot is not None
- assert [layer.lifecycle_state for layer in runs[1].session_snapshot.layers] == [
- LifecycleState.CLOSED,
- LifecycleState.CLOSED,
- ]
-
-
-def test_concurrent_enters_do_not_share_layer_instances() -> None:
- compositor = _compositor("trace")
-
- async def enter_once() -> tuple[int, list[str]]:
- async with compositor.enter() as run:
- layer = run.get_layer("trace", TraceLayer)
- await asyncio.sleep(0)
- return id(layer), layer.events
-
- async def run_concurrently() -> list[tuple[int, list[str]]]:
- return list(await asyncio.gather(enter_once(), enter_once()))
-
- results = asyncio.run(run_concurrently())
-
- assert results[0][0] != results[1][0]
- assert results[0][1] == ["create", "delete"]
- assert results[1][1] == ["create", "delete"]
-
-
-class ConfiguredLayerConfig(LayerConfig):
- value: str
-
- model_config = ConfigDict(extra="forbid")
-
-
-@dataclass(slots=True)
-class ConfiguredLayer(PlainLayer[NoLayerDeps, ConfiguredLayerConfig]):
- type_id = "test.configured"
-
- value: str
-
- hooks: list[str] = field(default_factory=list)
-
- @classmethod
- @override
- def from_config(cls, config: ConfiguredLayerConfig) -> "ConfiguredLayer":
- return cls(value=config.value)
-
- @override
- async def on_context_create(self) -> None:
- self.hooks.append(f"create:{self.config.value}")
-
-
-def test_custom_factory_is_called_each_enter_with_typed_config() -> None:
- calls: list[str] = []
-
- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:
- calls.append(config.value)
- return ConfiguredLayer(value=f"factory:{config.value}")
-
- compositor = Compositor(
- [LayerNode("configured", LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer))]
- )
-
- async def run() -> None:
- async with compositor.enter(configs={"configured": {"value": "one"}}) as first_run:
- first_layer = first_run.get_layer("configured", ConfiguredLayer)
- assert first_layer.value == "factory:one"
- assert first_layer.config.value == "one"
- async with compositor.enter(configs={"configured": ConfiguredLayerConfig(value="two")}) as second_run:
- second_layer = second_run.get_layer("configured", ConfiguredLayer)
- assert second_layer.value == "factory:two"
- assert second_layer.config.value == "two"
- assert second_layer is not first_layer
-
- asyncio.run(run())
-
- assert calls == ["one", "two"]
-
-
-def test_provider_rejects_reused_layer_instance_before_hooks_run() -> None:
- shared_layer = TraceLayer()
- compositor = Compositor(
- [
- LayerNode(
- "trace",
- LayerProvider.from_factory(layer_type=TraceLayer, create=lambda config: shared_layer),
- )
- ]
- )
-
- async def run() -> None:
- async with compositor.enter():
- pass
-
- with pytest.raises(ValueError, match="fresh layer instance"):
- async with compositor.enter():
- pass
-
- asyncio.run(run())
-
- assert shared_layer.events == ["create", "delete"]
-
-
-def test_configs_are_validated_by_node_name_before_factory_call() -> None:
- calls: list[str] = []
-
- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:
- calls.append(config.value)
- return ConfiguredLayer(value=config.value)
-
- compositor = Compositor(
- [LayerNode("configured", LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer))]
- )
-
- with pytest.raises(ValueError, match="unknown layer node names: missing"):
- asyncio.run(_enter_once(compositor, configs={"missing": {}}))
-
- with pytest.raises(ValidationError):
- asyncio.run(_enter_once(compositor, configs={"configured": {"unknown": "field"}}))
-
- assert calls == []
-
-
-def test_all_node_configs_are_validated_before_any_factory_runs() -> None:
- calls: list[str] = []
-
- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:
- calls.append(config.value)
- return ConfiguredLayer(value=config.value)
-
- provider = LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer)
- compositor = Compositor([LayerNode("first", provider), LayerNode("second", provider)])
-
- with pytest.raises(ValidationError):
- asyncio.run(
- _enter_once(
- compositor,
- configs={"first": {"value": "valid"}, "second": {"unknown": "field"}},
- )
- )
-
- assert calls == []
-
-
-def test_existing_config_model_instances_are_revalidated_before_factory_runs() -> None:
- calls: list[str] = []
-
- def create_layer(config: ConfiguredLayerConfig) -> ConfiguredLayer:
- calls.append(config.value)
- return ConfiguredLayer(value=config.value)
-
- compositor = Compositor(
- [LayerNode("configured", LayerProvider.from_factory(layer_type=ConfiguredLayer, create=create_layer))]
- )
- config = ConfiguredLayerConfig(value="valid")
- config.value = 123 # pyright: ignore[reportAttributeAccessIssue]
-
- with pytest.raises(ValidationError):
- asyncio.run(_enter_once(compositor, configs={"configured": config}))
-
- assert calls == []
-
-
-def test_existing_snapshot_model_instances_are_revalidated_before_factory_runs() -> None:
- calls = 0
-
- def create_layer(config: EmptyLayerConfig) -> TraceLayer:
- nonlocal calls
- calls += 1
- return TraceLayer()
-
- compositor = Compositor(
- [LayerNode("trace", LayerProvider.from_factory(layer_type=TraceLayer, create=create_layer))]
- )
- snapshot = CompositorSessionSnapshot.model_validate(
- {"layers": [{"name": "trace", "lifecycle_state": "suspended", "runtime_state": {}}]}
- )
- snapshot.layers[0].lifecycle_state = LifecycleState.ACTIVE
-
- with pytest.raises(ValidationError, match="ACTIVE is internal-only"):
- asyncio.run(_enter_once(compositor, session_snapshot=snapshot))
-
- assert calls == 0
-
-
-class RuntimeState(BaseModel):
- runtime_id: int | None = None
- resumed_runtime_id: int | None = None
- deleted_runtime_id: int | None = None
- body_value: str | None = None
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-@dataclass(slots=True)
-class RuntimeStateLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, RuntimeState]):
- next_id: Iterator[int] = field(default_factory=lambda: count(1))
-
- @override
- async def on_context_create(self) -> None:
- self.runtime_state.runtime_id = next(self.next_id)
-
- @override
- async def on_context_resume(self) -> None:
- self.runtime_state.resumed_runtime_id = self.runtime_state.runtime_id
-
- @override
- async def on_context_delete(self) -> None:
- self.runtime_state.deleted_runtime_id = self.runtime_state.runtime_id
-
-
-def test_snapshot_hydrates_runtime_state_and_exit_snapshots_from_layer_self() -> None:
- compositor = Compositor([LayerNode("state", RuntimeStateLayer)])
-
- async def create_suspend_resume_delete() -> tuple[CompositorSessionSnapshot, CompositorSessionSnapshot]:
- async with compositor.enter() as first_run:
- first_run.suspend_on_exit()
- assert first_run.session_snapshot is not None
-
- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:
- resumed_layer = resumed_run.get_layer("state", RuntimeStateLayer)
- assert isinstance(resumed_layer.runtime_state, RuntimeState)
- assert resumed_layer.runtime_state.runtime_id == 1
- assert resumed_layer.runtime_state.resumed_runtime_id == 1
- resumed_layer.runtime_state.body_value = "mutated on self"
- assert resumed_run.session_snapshot is not None
- return first_run.session_snapshot, resumed_run.session_snapshot
-
- suspended_snapshot, closed_snapshot = asyncio.run(create_suspend_resume_delete())
-
- assert suspended_snapshot.model_dump(mode="json") == {
- "schema_version": 1,
- "layers": [
- {
- "name": "state",
- "lifecycle_state": "suspended",
- "runtime_state": {
- "runtime_id": 1,
- "resumed_runtime_id": None,
- "deleted_runtime_id": None,
- "body_value": None,
- },
- }
- ],
- }
- assert closed_snapshot.model_dump(mode="json") == {
- "schema_version": 1,
- "layers": [
- {
- "name": "state",
- "lifecycle_state": "closed",
- "runtime_state": {
- "runtime_id": 1,
- "resumed_runtime_id": 1,
- "deleted_runtime_id": 1,
- "body_value": "mutated on self",
- },
- }
- ],
- }
-
-
-def test_run_snapshot_rejects_active_layers() -> None:
- compositor = _compositor("trace")
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- with pytest.raises(RuntimeError, match="Cannot snapshot active compositor run layers: trace"):
- active_run.snapshot_session()
-
- asyncio.run(run())
-
-
-def test_active_snapshot_input_is_rejected_before_factories_run() -> None:
- calls = 0
-
- def create_layer(config: EmptyLayerConfig) -> TraceLayer:
- nonlocal calls
- calls += 1
- return TraceLayer()
-
- compositor = Compositor(
- [LayerNode("trace", LayerProvider.from_factory(layer_type=TraceLayer, create=create_layer))]
- )
- active_snapshot = {"layers": [{"name": "trace", "lifecycle_state": "active", "runtime_state": {}}]}
-
- with pytest.raises(ValidationError, match="ACTIVE is internal-only"):
- CompositorSessionSnapshot.model_validate(active_snapshot)
-
- with pytest.raises(ValidationError, match="ACTIVE is internal-only"):
- asyncio.run(_enter_once(compositor, session_snapshot=active_snapshot))
-
- assert calls == 0
-
-
-def test_closed_snapshot_enter_is_rejected_before_hooks_run() -> None:
- created_layers: list[TraceLayer] = []
-
- def create_layer(config: EmptyLayerConfig) -> TraceLayer:
- layer = TraceLayer()
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [LayerNode("trace", LayerProvider.from_factory(layer_type=TraceLayer, create=create_layer))]
- )
- closed_snapshot = {"layers": [{"name": "trace", "lifecycle_state": "closed", "runtime_state": {}}]}
-
- with pytest.raises(RuntimeError, match="CLOSED snapshots cannot be entered"):
- asyncio.run(_enter_once(compositor, session_snapshot=closed_snapshot))
-
- assert len(created_layers) == 1
- assert created_layers[0].events == []
-
-
-class ResourceState(BaseModel):
- created_with_resource: bool = False
- deleted_with_resource: bool = False
- saw_dependency_resource: bool = False
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-@dataclass(slots=True)
-class ParentResourceLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, ResourceState]):
- events: list[str] = field(default_factory=list)
- live_resource: object | None = None
-
- @override
- @asynccontextmanager
- async def resource_context(self) -> AsyncGenerator[None]:
- self.events.append("parent.resource.enter")
- self.live_resource = object()
- try:
- yield
- finally:
- self.events.append("parent.resource.exit")
- self.live_resource = None
-
- @override
- async def on_context_create(self) -> None:
- assert self.live_resource is not None
- self.events.append("parent.create")
- self.runtime_state.created_with_resource = True
-
- @override
- async def on_context_delete(self) -> None:
- assert self.live_resource is not None
- self.events.append("parent.delete")
- self.runtime_state.deleted_with_resource = True
-
- @override
- async def on_context_suspend(self) -> None:
- assert self.live_resource is not None
- self.events.append("parent.suspend")
-
-
-class ChildResourceDeps(NoLayerDeps):
- parent: ParentResourceLayer # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-@dataclass(slots=True)
-class ChildResourceLayer(PlainLayer[ChildResourceDeps, EmptyLayerConfig, ResourceState]):
- events: list[str] = field(default_factory=list)
- live_resource: object | None = None
-
- @override
- @asynccontextmanager
- async def resource_context(self) -> AsyncGenerator[None]:
- self.events.append("child.resource.enter")
- self.live_resource = object()
- try:
- yield
- finally:
- self.events.append("child.resource.exit")
- self.live_resource = None
-
- @override
- async def on_context_create(self) -> None:
- assert self.live_resource is not None
- self.events.append("child.create")
- self.runtime_state.created_with_resource = True
- self.runtime_state.saw_dependency_resource = self.deps.parent.live_resource is not None
-
- @override
- async def on_context_delete(self) -> None:
- assert self.live_resource is not None
- self.events.append("child.delete")
- self.runtime_state.deleted_with_resource = True
-
-
-@dataclass(slots=True)
-class CreateFailureResourceLayer(PlainLayer[NoLayerDeps]):
- events: list[str] = field(default_factory=list)
- live_resource: bool = False
-
- @override
- @asynccontextmanager
- async def resource_context(self) -> AsyncGenerator[None]:
- self.events.append("resource.enter")
- self.live_resource = True
- try:
- yield
- finally:
- self.events.append("resource.exit")
- self.live_resource = False
-
- @override
- async def on_context_create(self) -> None:
- assert self.live_resource is True
- self.events.append("create")
- raise RuntimeError("create failed")
-
- @override
- async def on_context_delete(self) -> None:
- self.events.append("delete")
-
-
-@dataclass(slots=True)
-class DeleteFailureResourceLayer(PlainLayer[NoLayerDeps]):
- events: list[str] = field(default_factory=list)
- live_resource: bool = False
-
- @override
- @asynccontextmanager
- async def resource_context(self) -> AsyncGenerator[None]:
- self.events.append("resource.enter")
- self.live_resource = True
- try:
- yield
- finally:
- self.events.append("resource.exit")
- self.live_resource = False
-
- @override
- async def on_context_create(self) -> None:
- assert self.live_resource is True
- self.events.append("create")
-
- @override
- async def on_context_delete(self) -> None:
- assert self.live_resource is True
- self.events.append("delete")
- raise RuntimeError("delete failed")
-
-
-class ResumeResourceState(BaseModel):
- created_with_resource: bool = False
- resumed_with_resource: bool = False
- suspended_with_resource: bool = False
- deleted_with_resource: bool = False
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-@dataclass(slots=True)
-class SuspendResumeResourceLayer(PlainLayer[NoLayerDeps, EmptyLayerConfig, ResumeResourceState]):
- events: list[str]
- next_resource_id: Iterator[int]
- live_resource: str | None = None
-
- @override
- @asynccontextmanager
- async def resource_context(self) -> AsyncGenerator[None]:
- self.live_resource = f"resource-{next(self.next_resource_id)}"
- self.events.append(f"resource.enter:{self.live_resource}")
- try:
- yield
- finally:
- assert self.live_resource is not None
- self.events.append(f"resource.exit:{self.live_resource}")
- self.live_resource = None
-
- @override
- async def on_context_create(self) -> None:
- assert self.live_resource is not None
- self.events.append(f"create:{self.live_resource}")
- self.runtime_state.created_with_resource = True
-
- @override
- async def on_context_resume(self) -> None:
- assert self.live_resource is not None
- self.events.append(f"resume:{self.live_resource}")
- self.runtime_state.resumed_with_resource = True
-
- @override
- async def on_context_suspend(self) -> None:
- assert self.live_resource is not None
- self.events.append(f"suspend:{self.live_resource}")
- self.runtime_state.suspended_with_resource = True
-
- @override
- async def on_context_delete(self) -> None:
- assert self.live_resource is not None
- self.events.append(f"delete:{self.live_resource}")
- self.runtime_state.deleted_with_resource = True
-
-
-class CreateFailureChildResourceLayer(ChildResourceLayer):
- @override
- async def on_context_create(self) -> None:
- assert self.live_resource is not None
- self.events.append("child.create")
- raise RuntimeError("child create failed")
-
-
-class SuspendFailureChildResourceLayer(ChildResourceLayer):
- @override
- async def on_context_suspend(self) -> None:
- assert self.live_resource is not None
- self.events.append("child.suspend")
- raise RuntimeError("child suspend failed")
-
-
-def test_resource_context_wraps_hooks_and_body_in_dependency_order() -> None:
- events: list[str] = []
- compositor = Compositor(
- [
- LayerNode(
- "parent",
- LayerProvider.from_factory(
- layer_type=ParentResourceLayer,
- create=lambda config: ParentResourceLayer(events),
- ),
- ),
- LayerNode(
- "child",
- LayerProvider.from_factory(
- layer_type=ChildResourceLayer,
- create=lambda config: ChildResourceLayer(events),
- ),
- deps={"parent": "parent"},
- ),
- ]
- )
-
- async def run() -> CompositorSessionSnapshot:
- async with compositor.enter() as active_run:
- parent = active_run.get_layer("parent", ParentResourceLayer)
- child = active_run.get_layer("child", ChildResourceLayer)
- assert parent.live_resource is not None
- assert child.live_resource is not None
- assert child.deps.parent is parent
- events.append("body")
- assert active_run.session_snapshot is not None
- assert parent.live_resource is None
- assert child.live_resource is None
- return active_run.session_snapshot
-
- snapshot = asyncio.run(run())
-
- assert events == [
- "parent.resource.enter",
- "parent.create",
- "child.resource.enter",
- "child.create",
- "body",
- "child.delete",
- "child.resource.exit",
- "parent.delete",
- "parent.resource.exit",
- ]
- assert snapshot.model_dump(mode="json") == {
- "schema_version": 1,
- "layers": [
- {
- "name": "parent",
- "lifecycle_state": "closed",
- "runtime_state": {
- "created_with_resource": True,
- "deleted_with_resource": True,
- "saw_dependency_resource": False,
- },
- },
- {
- "name": "child",
- "lifecycle_state": "closed",
- "runtime_state": {
- "created_with_resource": True,
- "deleted_with_resource": True,
- "saw_dependency_resource": True,
- },
- },
- ],
- }
-
-
-def test_resource_context_wraps_resume_and_suspend_with_fresh_resource_scope() -> None:
- events: list[str] = []
- resource_ids = count(1)
- created_layers: list[SuspendResumeResourceLayer] = []
-
- def create_layer(config: EmptyLayerConfig) -> SuspendResumeResourceLayer:
- layer = SuspendResumeResourceLayer(events=events, next_resource_id=resource_ids)
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [LayerNode("trace", LayerProvider.from_factory(layer_type=SuspendResumeResourceLayer, create=create_layer))]
- )
-
- async def run() -> tuple[CompositorSessionSnapshot, CompositorSessionSnapshot]:
- async with compositor.enter() as first_run:
- first_layer = first_run.get_layer("trace", SuspendResumeResourceLayer)
- assert first_layer.live_resource == "resource-1"
- first_run.suspend_on_exit()
- assert first_run.session_snapshot is not None
-
- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:
- resumed_layer = resumed_run.get_layer("trace", SuspendResumeResourceLayer)
- assert resumed_layer.live_resource == "resource-2"
- assert resumed_layer.live_resource != "resource-1"
- assert resumed_run.session_snapshot is not None
- return first_run.session_snapshot, resumed_run.session_snapshot
-
- suspended_snapshot, resumed_snapshot = asyncio.run(run())
-
- assert len(created_layers) == 2
- assert all(layer.live_resource is None for layer in created_layers)
- assert events == [
- "resource.enter:resource-1",
- "create:resource-1",
- "suspend:resource-1",
- "resource.exit:resource-1",
- "resource.enter:resource-2",
- "resume:resource-2",
- "delete:resource-2",
- "resource.exit:resource-2",
- ]
- assert suspended_snapshot.model_dump(mode="json") == {
- "schema_version": 1,
- "layers": [
- {
- "name": "trace",
- "lifecycle_state": "suspended",
- "runtime_state": {
- "created_with_resource": True,
- "resumed_with_resource": False,
- "suspended_with_resource": True,
- "deleted_with_resource": False,
- },
- }
- ],
- }
- assert resumed_snapshot.model_dump(mode="json") == {
- "schema_version": 1,
- "layers": [
- {
- "name": "trace",
- "lifecycle_state": "closed",
- "runtime_state": {
- "created_with_resource": True,
- "resumed_with_resource": True,
- "suspended_with_resource": True,
- "deleted_with_resource": True,
- },
- }
- ],
- }
-
-
-def test_resource_context_exits_when_run_body_raises() -> None:
- events: list[str] = []
- created_layers: list[ParentResourceLayer | ChildResourceLayer] = []
-
- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:
- layer = ParentResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- def create_child(config: EmptyLayerConfig) -> ChildResourceLayer:
- layer = ChildResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [
- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),
- LayerNode(
- "child",
- LayerProvider.from_factory(layer_type=ChildResourceLayer, create=create_child),
- deps={"parent": "parent"},
- ),
- ]
- )
-
- async def run() -> None:
- async with compositor.enter():
- events.append("body")
- raise RuntimeError("body failed")
-
- with pytest.raises(RuntimeError, match="body failed"):
- asyncio.run(run())
-
- assert [layer.live_resource for layer in created_layers] == [None, None]
- assert events == [
- "parent.resource.enter",
- "parent.create",
- "child.resource.enter",
- "child.create",
- "body",
- "child.delete",
- "child.resource.exit",
- "parent.delete",
- "parent.resource.exit",
- ]
-
-
-def test_resource_context_exits_when_run_body_is_cancelled() -> None:
- events: list[str] = []
- created_layers: list[ParentResourceLayer | ChildResourceLayer] = []
-
- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:
- layer = ParentResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- def create_child(config: EmptyLayerConfig) -> ChildResourceLayer:
- layer = ChildResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [
- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),
- LayerNode(
- "child",
- LayerProvider.from_factory(layer_type=ChildResourceLayer, create=create_child),
- deps={"parent": "parent"},
- ),
- ]
- )
-
- async def run() -> None:
- async with compositor.enter():
- events.append("body")
- task = asyncio.current_task()
- assert task is not None
- task.cancel()
- await asyncio.sleep(0)
-
- with pytest.raises(asyncio.CancelledError):
- asyncio.run(run())
-
- assert [layer.live_resource for layer in created_layers] == [None, None]
- assert events == [
- "parent.resource.enter",
- "parent.create",
- "child.resource.enter",
- "child.create",
- "body",
- "child.delete",
- "child.resource.exit",
- "parent.delete",
- "parent.resource.exit",
- ]
-
-
-def test_dependency_resource_contexts_exit_when_child_create_fails() -> None:
- events: list[str] = []
- created_layers: list[ParentResourceLayer | CreateFailureChildResourceLayer] = []
-
- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:
- layer = ParentResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- def create_child(config: EmptyLayerConfig) -> CreateFailureChildResourceLayer:
- layer = CreateFailureChildResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [
- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),
- LayerNode(
- "child",
- LayerProvider.from_factory(layer_type=CreateFailureChildResourceLayer, create=create_child),
- deps={"parent": "parent"},
- ),
- ]
- )
-
- with pytest.raises(RuntimeError, match="child create failed"):
- asyncio.run(_enter_once(compositor))
-
- assert [layer.live_resource for layer in created_layers] == [None, None]
- assert events == [
- "parent.resource.enter",
- "parent.create",
- "child.resource.enter",
- "child.create",
- "child.resource.exit",
- "parent.delete",
- "parent.resource.exit",
- ]
-
-
-def test_dependency_resource_contexts_exit_when_child_suspend_fails() -> None:
- events: list[str] = []
- created_layers: list[ParentResourceLayer | SuspendFailureChildResourceLayer] = []
-
- def create_parent(config: EmptyLayerConfig) -> ParentResourceLayer:
- layer = ParentResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- def create_child(config: EmptyLayerConfig) -> SuspendFailureChildResourceLayer:
- layer = SuspendFailureChildResourceLayer(events)
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [
- LayerNode("parent", LayerProvider.from_factory(layer_type=ParentResourceLayer, create=create_parent)),
- LayerNode(
- "child",
- LayerProvider.from_factory(layer_type=SuspendFailureChildResourceLayer, create=create_child),
- deps={"parent": "parent"},
- ),
- ]
- )
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- events.append("body")
- active_run.suspend_on_exit()
-
- with pytest.raises(RuntimeError, match="child suspend failed"):
- asyncio.run(run())
-
- assert [layer.live_resource for layer in created_layers] == [None, None]
- assert events == [
- "parent.resource.enter",
- "parent.create",
- "child.resource.enter",
- "child.create",
- "body",
- "child.suspend",
- "child.resource.exit",
- "parent.suspend",
- "parent.resource.exit",
- ]
-
-
-def test_resource_context_exits_when_create_hook_raises() -> None:
- created_layers: list[CreateFailureResourceLayer] = []
-
- def create_layer(config: EmptyLayerConfig) -> CreateFailureResourceLayer:
- layer = CreateFailureResourceLayer()
- created_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [
- LayerNode(
- "trace",
- LayerProvider.from_factory(layer_type=CreateFailureResourceLayer, create=create_layer),
- )
- ]
- )
-
- with pytest.raises(RuntimeError, match="create failed"):
- asyncio.run(_enter_once(compositor))
-
- assert len(created_layers) == 1
- assert created_layers[0].events == ["resource.enter", "create", "resource.exit"]
- assert created_layers[0].live_resource is False
-
-
-def test_resource_context_exits_when_delete_hook_raises() -> None:
- deleted_layers: list[DeleteFailureResourceLayer] = []
-
- def create_layer(config: EmptyLayerConfig) -> DeleteFailureResourceLayer:
- layer = DeleteFailureResourceLayer()
- deleted_layers.append(layer)
- return layer
-
- compositor = Compositor(
- [
- LayerNode(
- "trace",
- LayerProvider.from_factory(layer_type=DeleteFailureResourceLayer, create=create_layer),
- )
- ]
- )
-
- with pytest.raises(RuntimeError, match="delete failed"):
- asyncio.run(_enter_once(compositor))
-
- assert len(deleted_layers) == 1
- assert deleted_layers[0].events == ["resource.enter", "create", "delete", "resource.exit"]
- assert deleted_layers[0].live_resource is False
-
-
-async def _enter_once(
- compositor: Compositor,
- *,
- configs: dict[str, object] | None = None,
- session_snapshot: object | None = None,
-) -> None:
- async with compositor.enter(
- configs=configs, # pyright: ignore[reportArgumentType]
- session_snapshot=session_snapshot, # pyright: ignore[reportArgumentType]
- ):
- pass
diff --git a/dify-agent/tests/local/agenton/compositor/test_transformers.py b/dify-agent/tests/local/agenton/compositor/test_transformers.py
deleted file mode 100644
index 56a41d9fe09..00000000000
--- a/dify-agent/tests/local/agenton/compositor/test_transformers.py
+++ /dev/null
@@ -1,156 +0,0 @@
-import asyncio
-from collections.abc import Callable, Sequence
-from dataclasses import dataclass
-from inspect import Parameter, signature
-
-from typing_extensions import override
-
-from agenton.compositor import Compositor, CompositorTransformerKwargs, LayerNode, LayerProvider
-from agenton.layers import NoLayerDeps, PlainLayer, PlainPromptType, PlainToolType, PlainUserPromptType
-
-type ToolCallable = Callable[..., object]
-type WrappedPrompt = tuple[str, str]
-type WrappedUserPrompt = tuple[str, str]
-
-
-@dataclass(slots=True)
-class PromptAndToolLayer(PlainLayer[NoLayerDeps]):
- prefix: list[str]
- user: list[str]
- suffix: list[str]
- tool_entries: list[ToolCallable]
-
- @property
- @override
- def prefix_prompts(self) -> list[str]:
- return self.prefix
-
- @property
- @override
- def suffix_prompts(self) -> list[str]:
- return self.suffix
-
- @property
- @override
- def user_prompts(self) -> list[str]:
- return self.user
-
- @property
- @override
- def tools(self) -> list[ToolCallable]:
- return self.tool_entries
-
-
-def base_tool() -> str:
- return "base"
-
-
-def wrapped_tool() -> str:
- return "wrapped"
-
-
-def wrap_prompts(prompts: Sequence[PlainPromptType]) -> list[WrappedPrompt]:
- return [("wrapped", prompt.value) for prompt in prompts]
-
-
-def wrap_user_prompts(prompts: Sequence[PlainUserPromptType]) -> list[WrappedUserPrompt]:
- return [("wrapped-user", prompt.value) for prompt in prompts]
-
-
-def describe_tools(tools: Sequence[PlainToolType]) -> list[str]:
- return [tool.value.__name__ for tool in tools]
-
-
-def prompt_tool_provider(
- *,
- prefix: list[str] | None = None,
- user: list[str] | None = None,
- suffix: list[str] | None = None,
- tool_entries: list[ToolCallable] | None = None,
-) -> LayerProvider[PromptAndToolLayer]:
- return LayerProvider.from_factory(
- layer_type=PromptAndToolLayer,
- create=lambda config: PromptAndToolLayer(
- prefix=list(prefix or []),
- user=list(user or []),
- suffix=list(suffix or []),
- tool_entries=list(tool_entries or []),
- ),
- )
-
-
-def test_compositor_transformer_kwargs_keys_match_constructor_parameters() -> None:
- transformer_kwargs = set(CompositorTransformerKwargs.__required_keys__)
- parameters = signature(Compositor).parameters
-
- assert CompositorTransformerKwargs.__optional_keys__ == frozenset()
- assert transformer_kwargs == {name for name in parameters if name.endswith("_transformer")}
- assert all(parameters[name].kind is Parameter.KEYWORD_ONLY for name in transformer_kwargs)
-
-
-def test_compositor_transformer_kwargs_keys_match_from_config_parameters() -> None:
- transformer_kwargs = set(CompositorTransformerKwargs.__required_keys__)
- parameters = signature(Compositor.from_config).parameters
-
- assert transformer_kwargs == {name for name in parameters if name.endswith("_transformer")}
- assert all(parameters[name].kind is Parameter.KEYWORD_ONLY for name in transformer_kwargs)
-
-
-def test_compositor_transforms_prompts_to_another_type_after_layer_ordering() -> None:
- compositor: Compositor[WrappedPrompt, PlainToolType, PlainPromptType, PlainToolType] = Compositor(
- [
- LayerNode("first", prompt_tool_provider(prefix=["first-prefix"], suffix=["first-suffix"])),
- LayerNode("second", prompt_tool_provider(prefix=["second-prefix"], suffix=["second-suffix"])),
- ],
- prompt_transformer=wrap_prompts,
- )
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- assert active_run.prompts == [
- ("wrapped", "first-prefix"),
- ("wrapped", "second-prefix"),
- ("wrapped", "second-suffix"),
- ("wrapped", "first-suffix"),
- ]
-
- asyncio.run(run())
-
-
-def test_compositor_transforms_tools_to_another_type_after_layer_aggregation() -> None:
- compositor: Compositor[PlainPromptType, str, PlainPromptType, PlainToolType] = Compositor(
- [LayerNode("tools", prompt_tool_provider(tool_entries=[base_tool, wrapped_tool]))],
- tool_transformer=describe_tools,
- )
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- assert active_run.tools == ["base_tool", "wrapped_tool"]
-
- asyncio.run(run())
-
-
-def test_compositor_transforms_user_prompts_after_layer_ordering() -> None:
- compositor: Compositor[
- PlainPromptType,
- PlainToolType,
- PlainPromptType,
- PlainToolType,
- WrappedUserPrompt,
- PlainUserPromptType,
- ] = Compositor(
- [
- LayerNode("first", prompt_tool_provider(user=["first-user"])),
- LayerNode("second", prompt_tool_provider(user=["second-user"])),
- ],
- user_prompt_transformer=wrap_user_prompts,
- )
-
- async def run() -> None:
- async with compositor.enter() as active_run:
- assert active_run.user_prompts == [
- ("wrapped-user", "first-user"),
- ("wrapped-user", "second-user"),
- ]
-
- asyncio.run(run())
diff --git a/dify-agent/tests/local/agenton/layers/__init__.py b/dify-agent/tests/local/agenton/layers/__init__.py
deleted file mode 100644
index 8b137891791..00000000000
--- a/dify-agent/tests/local/agenton/layers/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/dify-agent/tests/local/agenton/layers/test_layer_deps.py b/dify-agent/tests/local/agenton/layers/test_layer_deps.py
deleted file mode 100644
index 1ab0c543e20..00000000000
--- a/dify-agent/tests/local/agenton/layers/test_layer_deps.py
+++ /dev/null
@@ -1,15 +0,0 @@
-import pytest
-
-from agenton.layers import LayerDeps
-from agenton_collections.layers.plain import ObjectLayer, PromptLayer
-
-
-class ObjectLayerDeps(LayerDeps):
- """Deps container used to exercise runtime dependency validation."""
-
- object_layer: ObjectLayer[str] # pyright: ignore[reportUninitializedInstanceVariable]
-
-
-def test_layer_deps_rejects_mismatched_runtime_layer_class() -> None:
- with pytest.raises(TypeError, match="should be of type 'ObjectLayer'"):
- ObjectLayerDeps(object_layer=PromptLayer())
diff --git a/dify-agent/tests/local/agenton/layers/test_schema_inference.py b/dify-agent/tests/local/agenton/layers/test_schema_inference.py
deleted file mode 100644
index 55af512e544..00000000000
--- a/dify-agent/tests/local/agenton/layers/test_schema_inference.py
+++ /dev/null
@@ -1,92 +0,0 @@
-from dataclasses import dataclass
-
-from pydantic import BaseModel, ConfigDict
-
-from agenton.compositor import LayerProvider
-from agenton.layers import (
- EmptyLayerConfig,
- EmptyRuntimeState,
- LayerConfig,
- NoLayerDeps,
- PlainLayer,
-)
-
-
-class InferredConfig(LayerConfig):
- value: str = "configured"
-
- model_config = ConfigDict(extra="forbid")
-
-
-class InferredState(BaseModel):
- count: int = 0
-
- model_config = ConfigDict(extra="forbid", validate_assignment=True)
-
-
-@dataclass(slots=True)
-class GenericSchemaLayer(PlainLayer[NoLayerDeps, InferredConfig, InferredState]):
- type_id = "test.generic-schema"
-
- @classmethod
- def from_config(cls, config: InferredConfig) -> "GenericSchemaLayer":
- return cls()
-
- async def on_context_create(self) -> None:
- self.runtime_state.count += 1
-
-
-@dataclass(slots=True)
-class DefaultSchemaLayer(PlainLayer[NoLayerDeps]):
- type_id = "test.default-schema"
-
-
-def test_layer_infers_config_and_runtime_state_from_generics() -> None:
- layer = GenericSchemaLayer()
- layer.runtime_state = InferredState(count=3)
-
- assert GenericSchemaLayer.config_type is InferredConfig
- assert GenericSchemaLayer.runtime_state_type is InferredState
- assert isinstance(layer.runtime_state, InferredState)
- assert layer.runtime_state.count == 3
-
-
-def test_layer_uses_empty_schema_defaults_when_omitted() -> None:
- layer = DefaultSchemaLayer()
-
- assert DefaultSchemaLayer.config_type is EmptyLayerConfig
- assert DefaultSchemaLayer.runtime_state_type is EmptyRuntimeState
- assert isinstance(layer.runtime_state, EmptyRuntimeState)
-
-
-def test_invalid_declared_schema_type_is_rejected_clearly() -> None:
- try:
-
- class InvalidSchemaLayer(PlainLayer[NoLayerDeps]):
- config_type = dict # pyright: ignore[reportAssignmentType]
-
- except TypeError as e:
- assert str(e) == "InvalidSchemaLayer.config_type must be a LayerConfig subclass."
- else:
- raise AssertionError("Expected TypeError.")
-
- try:
-
- class InvalidGenericSchemaLayer(PlainLayer[NoLayerDeps, dict[str, object]]): # pyright: ignore[reportInvalidTypeArguments]
- pass
-
- except TypeError as e:
- assert str(e) == "InvalidGenericSchemaLayer.config_type must be a LayerConfig subclass."
- else:
- raise AssertionError("Expected TypeError.")
-
-
-def test_layer_provider_uses_inferred_schema_types() -> None:
- provider = LayerProvider.from_layer_type(GenericSchemaLayer)
-
- layer = provider.create_layer({"value": "configured"})
-
- assert provider.type_id == "test.generic-schema"
- assert provider.layer_type.config_type is InferredConfig
- assert provider.layer_type.runtime_state_type is InferredState
- assert isinstance(layer.config, InferredConfig)
diff --git a/dify-agent/tests/local/agenton_collections/__init__.py b/dify-agent/tests/local/agenton_collections/__init__.py
deleted file mode 100644
index 8b137891791..00000000000
--- a/dify-agent/tests/local/agenton_collections/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/dify-agent/tests/local/agenton_collections/layers/plain/__init__.py b/dify-agent/tests/local/agenton_collections/layers/plain/__init__.py
deleted file mode 100644
index 8b137891791..00000000000
--- a/dify-agent/tests/local/agenton_collections/layers/plain/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/dify-agent/tests/local/agenton_collections/layers/plain/test_basic.py b/dify-agent/tests/local/agenton_collections/layers/plain/test_basic.py
deleted file mode 100644
index 45928d079bd..00000000000
--- a/dify-agent/tests/local/agenton_collections/layers/plain/test_basic.py
+++ /dev/null
@@ -1,6 +0,0 @@
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayer
-
-
-def test_prompt_layer_type_id_constant_matches_implementation_class() -> None:
- assert PLAIN_PROMPT_LAYER_TYPE_ID == "plain.prompt"
- assert PromptLayer.type_id == PLAIN_PROMPT_LAYER_TYPE_ID
diff --git a/dify-agent/tests/local/agenton_collections/layers/plain/test_dynamic_tools.py b/dify-agent/tests/local/agenton_collections/layers/plain/test_dynamic_tools.py
deleted file mode 100644
index 213d7ff992a..00000000000
--- a/dify-agent/tests/local/agenton_collections/layers/plain/test_dynamic_tools.py
+++ /dev/null
@@ -1,75 +0,0 @@
-import asyncio
-
-import pytest
-from pydantic_ai import Tool
-
-from agenton_collections.layers.plain import DynamicToolsLayer, ObjectLayer, with_object
-
-
-class Profile:
- """Profile object used by object-bound tool tests."""
-
- name: str
-
- def __init__(self, name: str) -> None:
- self.name = name
-
-
-class OtherProfile:
- """Different runtime object used to trigger object mismatch checks."""
-
-
-@with_object(Profile)
-def greet(profile: Profile, topic: str) -> str:
- return f"{profile.name}: {topic}"
-
-
-def test_with_object_rejects_tool_without_object_parameter() -> None:
- def tool() -> str:
- return "unused"
-
- with pytest.raises(ValueError, match="must accept the object dependency"):
- with_object(Profile)(tool) # pyright: ignore[reportArgumentType]
-
-
-def test_with_object_rejects_first_parameter_annotation_mismatch() -> None:
- def tool(profile: OtherProfile) -> str:
- return repr(profile)
-
- with pytest.raises(TypeError, match="first parameter should accept 'Profile'"):
- with_object(Profile)(tool) # pyright: ignore[reportArgumentType]
-
-
-def test_dynamic_tools_layer_rejects_mismatched_runtime_object_value() -> None:
- layer = DynamicToolsLayer[Profile](tool_entries=(greet,))
- layer.bind_deps({"object_layer": ObjectLayer[OtherProfile](OtherProfile())})
-
- with pytest.raises(TypeError, match="expected object dependency of type 'Profile'"):
- layer.tools
-
-
-def public_greet(topic: str) -> str:
- return f"Ada: {topic}"
-
-
-def test_dynamic_tools_layer_binds_object_as_pydantic_ai_equivalent_tool() -> None:
- layer = DynamicToolsLayer[Profile](tool_entries=(greet,))
- layer.bind_deps({"object_layer": ObjectLayer[Profile](Profile("Ada"))})
-
- expected_tool = Tool(public_greet, name="greet")
- dynamic_tool = Tool(layer.tools[0], name="greet")
- dynamic_result = asyncio.run(
- dynamic_tool.function_schema.call(
- {"topic": "layer composition"},
- None, # pyright: ignore[reportArgumentType]
- )
- )
- expected_result = asyncio.run(
- expected_tool.function_schema.call(
- {"topic": "layer composition"},
- None, # pyright: ignore[reportArgumentType]
- )
- )
-
- assert dynamic_tool.tool_def == expected_tool.tool_def
- assert dynamic_result == expected_result
diff --git a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_bridge.py b/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_bridge.py
deleted file mode 100644
index 12a93959de3..00000000000
--- a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_bridge.py
+++ /dev/null
@@ -1,56 +0,0 @@
-from collections.abc import Callable
-from dataclasses import dataclass
-from typing import cast
-
-from pydantic_ai import RunContext, Tool
-
-from agenton_collections.layers.pydantic_ai import PydanticAIBridgeLayer
-
-
-@dataclass(frozen=True, slots=True)
-class Profile:
- name: str
-
-
-def profile_prompt(ctx: RunContext[Profile]) -> str:
- return f"Profile: {ctx.deps.name}"
-
-
-def existing_tool(ctx: RunContext[Profile]) -> str:
- return ctx.deps.name
-
-
-def raw_tool(ctx: RunContext[Profile], topic: str) -> str:
- return f"{ctx.deps.name}: {topic}"
-
-
-def test_pydantic_ai_bridge_layer_accepts_mixed_string_and_function_prompts() -> None:
- layer = PydanticAIBridgeLayer[Profile](
- prefix=("plain prefix", profile_prompt),
- user=("first user", "second user"),
- suffix="plain suffix",
- )
-
- prefix_prompts = layer.prefix_prompts
- user_prompts = layer.user_prompts
- suffix_prompts = layer.suffix_prompts
-
- plain_prefix = cast(Callable[[], str], prefix_prompts[0])
- plain_suffix = cast(Callable[[], str], suffix_prompts[0])
- assert plain_prefix() == "plain prefix"
- assert prefix_prompts[1] is profile_prompt
- assert user_prompts == ["first user", "second user"]
- assert plain_suffix() == "plain suffix"
-
-
-def test_pydantic_ai_bridge_layer_accepts_mixed_tool_and_tool_function_entries() -> None:
- pydantic_ai_tool = Tool(existing_tool)
- layer = PydanticAIBridgeLayer[Profile](
- tool_entries=(pydantic_ai_tool, raw_tool),
- )
-
- tools = layer.tools
-
- assert tools[0] is pydantic_ai_tool
- assert isinstance(tools[1], Tool)
- assert tools[1].function is raw_tool
diff --git a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_history.py b/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_history.py
deleted file mode 100644
index fbe1405f534..00000000000
--- a/dify-agent/tests/local/agenton_collections/layers/pydantic_ai/test_history.py
+++ /dev/null
@@ -1,96 +0,0 @@
-import asyncio
-
-from pydantic_ai.messages import ModelMessage, ModelRequest, ModelResponse, TextPart, UserPromptPart
-
-from agenton.compositor import Compositor, LayerNode
-from agenton.layers import LifecycleState
-from agenton_collections.layers.pydantic_ai import PydanticAIHistoryLayer, PydanticAIHistoryRuntimeState
-
-
-def test_pydantic_ai_history_layer_starts_empty_and_contributes_no_prompts_or_tools() -> None:
- layer = PydanticAIHistoryLayer()
-
- assert layer.message_history == []
- assert list(layer.prefix_prompts) == []
- assert list(layer.suffix_prompts) == []
- assert list(layer.user_prompts) == []
- assert list(layer.tools) == []
-
-
-def test_pydantic_ai_history_layer_replace_messages_saves_validated_copy() -> None:
- layer = PydanticAIHistoryLayer()
- messages = _sample_messages()
-
- layer.replace_messages(messages)
- borrowed_messages = layer.message_history
-
- assert borrowed_messages == messages
- assert borrowed_messages is not messages
-
- messages.append(ModelResponse(parts=[TextPart(content="later")]))
- assert layer.message_history != messages
-
-
-def test_pydantic_ai_history_layer_append_messages_preserves_order_and_internal_state() -> None:
- layer = PydanticAIHistoryLayer()
- request, response = _sample_messages()
-
- layer.replace_messages([request])
- layer.append_messages((response,))
-
- borrowed_messages = layer.message_history
- borrowed_messages.clear()
-
- assert layer.message_history == [request, response]
-
-
-def test_pydantic_ai_history_layer_clear_removes_stored_messages() -> None:
- layer = PydanticAIHistoryLayer()
-
- layer.replace_messages(_sample_messages())
- layer.clear()
-
- assert layer.message_history == []
- assert layer.runtime_state.messages == []
-
-
-def test_pydantic_ai_history_runtime_state_round_trips_through_json_dump() -> None:
- messages = _sample_messages()
- runtime_state = PydanticAIHistoryRuntimeState(messages=messages)
-
- dumped_state = runtime_state.model_dump(mode="json")
- restored_state = PydanticAIHistoryRuntimeState.model_validate(dumped_state)
-
- assert restored_state.messages == messages
- assert isinstance(restored_state.messages[0], ModelRequest)
- assert isinstance(restored_state.messages[1], ModelResponse)
-
-
-def test_pydantic_ai_history_layer_messages_round_trip_through_session_snapshot() -> None:
- compositor = Compositor([LayerNode("history", PydanticAIHistoryLayer)])
- messages = _sample_messages()
-
- async def scenario() -> None:
- async with compositor.enter() as first_run:
- history_layer = first_run.get_layer("history", PydanticAIHistoryLayer)
- history_layer.replace_messages(messages)
- first_run.suspend_on_exit()
-
- assert first_run.session_snapshot is not None
- assert first_run.session_snapshot.layers[0].lifecycle_state is LifecycleState.SUSPENDED
-
- async with compositor.enter(session_snapshot=first_run.session_snapshot) as resumed_run:
- history_layer = resumed_run.get_layer("history", PydanticAIHistoryLayer)
-
- assert history_layer.message_history == messages
- assert isinstance(history_layer.runtime_state.messages[0], ModelRequest)
- assert isinstance(history_layer.runtime_state.messages[1], ModelResponse)
-
- asyncio.run(scenario())
-
-
-def _sample_messages() -> list[ModelMessage]:
- return [
- ModelRequest(parts=[UserPromptPart(content="Hello")]),
- ModelResponse(parts=[TextPart(content="Hi there")]),
- ]
diff --git a/dify-agent/tests/local/agenton_collections/transformers/test_pydantic_ai.py b/dify-agent/tests/local/agenton_collections/transformers/test_pydantic_ai.py
deleted file mode 100644
index 4ff49b1e1a3..00000000000
--- a/dify-agent/tests/local/agenton_collections/transformers/test_pydantic_ai.py
+++ /dev/null
@@ -1,85 +0,0 @@
-from collections.abc import Callable
-from typing import cast
-
-from pydantic_ai import Tool
-
-from agenton.layers.types import (
- PlainPromptType,
- PlainToolType,
- PlainUserPromptType,
- PydanticAIPromptType,
- PydanticAIToolType,
- PydanticAIUserPromptType,
-)
-from agenton_collections.transformers.pydantic_ai import PYDANTIC_AI_TRANSFORMERS
-
-
-def plain_tool(name: str) -> str:
- return f"hello {name}"
-
-
-def dynamic_prompt() -> str:
- return "dynamic prompt"
-
-
-def test_pydantic_ai_transformers_wrap_tagged_plain_prompts() -> None:
- prompts = [PlainPromptType("plain prompt")]
-
- result = PYDANTIC_AI_TRANSFORMERS["prompt_transformer"](prompts)
-
- assert len(result) == 1
- prompt_func = cast(Callable[[], str], result[0])
- assert prompt_func() == "plain prompt"
-
-
-def test_pydantic_ai_transformers_preserve_tagged_existing_prompt_functions() -> None:
- result = PYDANTIC_AI_TRANSFORMERS["prompt_transformer"]([PydanticAIPromptType(dynamic_prompt)])
-
- assert result == [dynamic_prompt]
-
-
-def test_pydantic_ai_transformers_accept_mixed_tagged_prompt_types() -> None:
- result = PYDANTIC_AI_TRANSFORMERS["prompt_transformer"](
- [PlainPromptType("plain prompt"), PydanticAIPromptType(dynamic_prompt)]
- )
-
- plain_prompt = cast(Callable[[], str], result[0])
- assert plain_prompt() == "plain prompt"
- assert result[1] is dynamic_prompt
-
-
-def test_pydantic_ai_transformers_accept_tagged_user_prompt_types() -> None:
- result = PYDANTIC_AI_TRANSFORMERS["user_prompt_transformer"](
- [PlainUserPromptType("plain user"), PydanticAIUserPromptType("pydantic user")]
- )
-
- assert result == ["plain user", "pydantic user"]
-
-
-def test_pydantic_ai_transformers_wrap_tagged_plain_tools() -> None:
- result = PYDANTIC_AI_TRANSFORMERS["tool_transformer"]([PlainToolType(plain_tool)])
-
- assert len(result) == 1
- tool = result[0]
- assert isinstance(tool, Tool)
- assert tool.function is plain_tool
-
-
-def test_pydantic_ai_transformers_preserve_tagged_existing_tools() -> None:
- pydantic_ai_tool = Tool(plain_tool)
-
- result = PYDANTIC_AI_TRANSFORMERS["tool_transformer"]([PydanticAIToolType(pydantic_ai_tool)])
-
- assert result == [pydantic_ai_tool]
-
-
-def test_pydantic_ai_transformers_accept_tagged_tool_types() -> None:
- pydantic_ai_tool = Tool(plain_tool)
-
- result = PYDANTIC_AI_TRANSFORMERS["tool_transformer"](
- [PlainToolType(plain_tool), PydanticAIToolType(pydantic_ai_tool)]
- )
-
- assert isinstance(result[0], Tool)
- assert result[0].function is plain_tool
- assert result[1] is pydantic_ai_tool
diff --git a/dify-agent/tests/local/dify_agent/client/test_client.py b/dify-agent/tests/local/dify_agent/client/test_client.py
index 3f2a4001786..c1bddce04e3 100644
--- a/dify-agent/tests/local/dify_agent/client/test_client.py
+++ b/dify-agent/tests/local/dify_agent/client/test_client.py
@@ -9,8 +9,7 @@ from typing import cast, override
import httpx
import pytest
-from agenton.compositor import CompositorSessionSnapshot
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID
+from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
from dify_agent.client import _client as client_module
from dify_agent.client import (
@@ -48,8 +47,8 @@ from dify_agent.protocol import (
def _create_run_payload() -> dict[str, object]:
return {
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "config": {"user": "hello"}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],
}
}
@@ -67,7 +66,7 @@ def _run_succeeded_event(*, event_id: str = "2-0", run_id: str = "run-1") -> Run
return RunSucceededEvent(
id=event_id,
run_id=run_id,
- data=RunSucceededEventData(output="done", session_snapshot=CompositorSessionSnapshot(layers=[])),
+ data=RunSucceededEventData(output="done", session_snapshot=SessionSnapshot(layers={})),
)
@@ -247,7 +246,7 @@ def test_async_methods_and_wait_run_parse_protocol_dtos() -> None:
def test_cancel_run_and_wait_sync_resumes_after_cursor_and_returns_cancelled_snapshot() -> None:
- snapshot = CompositorSessionSnapshot(layers=[])
+ snapshot = SessionSnapshot(layers={})
def handler(request: httpx.Request) -> httpx.Response:
if request.method == "POST":
diff --git a/dify-agent/tests/local/dify_agent/layers/ask_human/test_configs.py b/dify-agent/tests/local/dify_agent/layers/ask_human/test_configs.py
deleted file mode 100644
index f9b42220e03..00000000000
--- a/dify-agent/tests/local/dify_agent/layers/ask_human/test_configs.py
+++ /dev/null
@@ -1,73 +0,0 @@
-import pytest
-from pydantic import ValidationError
-
-import dify_agent.layers.ask_human as ask_human_exports
-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
-from dify_agent.layers.ask_human.schema import AskHumanToolArgs
-
-
-def test_ask_human_package_exports_client_safe_symbols_only() -> None:
- assert ask_human_exports.DIFY_ASK_HUMAN_LAYER_TYPE_ID == "dify.ask_human"
- assert ask_human_exports.__all__ == [
- "AskHumanAction",
- "AskHumanActionStyle",
- "AskHumanField",
- "AskHumanFieldType",
- "AskHumanFileField",
- "AskHumanFileListField",
- "AskHumanParagraphField",
- "AskHumanResultStatus",
- "AskHumanSelectField",
- "AskHumanSelectOption",
- "AskHumanSelectedAction",
- "AskHumanToolArgs",
- "AskHumanToolResult",
- "AskHumanUrgency",
- "DEFAULT_ASK_HUMAN_TOOL_DESCRIPTION",
- "DIFY_ASK_HUMAN_LAYER_TYPE_ID",
- "DifyAskHumanLayerConfig",
- ]
- assert not hasattr(ask_human_exports, "DifyAskHumanLayer")
-
-
-def test_ask_human_layer_config_defaults_and_effective_description() -> None:
- config = DifyAskHumanLayerConfig()
-
- assert DIFY_ASK_HUMAN_LAYER_TYPE_ID == "dify.ask_human"
- assert config.model_dump(mode="json") == {
- "enabled": True,
- "tool_name": "ask_human",
- "tool_description": None,
- "max_fields": 8,
- "max_actions": 4,
- "allowed_field_types": ["paragraph", "select"],
- "allow_file_fields": False,
- "max_markdown_chars": 8000,
- "max_question_chars": 1000,
- "max_field_label_chars": 120,
- "max_action_label_chars": 80,
- }
- assert "Ask a human for missing information" in config.effective_tool_description
-
-
-def test_ask_human_layer_config_rejects_invalid_tool_name() -> None:
- with pytest.raises(ValidationError, match="tool_name must be a valid tool identifier"):
- _ = DifyAskHumanLayerConfig(tool_name="ask-human")
-
-
-def test_ask_human_layer_config_rejects_file_field_types_when_disabled() -> None:
- with pytest.raises(ValidationError, match="cannot include file field types"):
- _ = DifyAskHumanLayerConfig(allowed_field_types=["paragraph", "file"])
-
-
-def test_ask_human_tool_args_reject_duplicate_field_names() -> None:
- with pytest.raises(ValidationError, match="field name 'comment' must be unique"):
- _ = AskHumanToolArgs.model_validate(
- {
- "question": "Need a reply",
- "fields": [
- {"type": "paragraph", "name": "comment", "label": "Comment"},
- {"type": "paragraph", "name": "comment", "label": "Another comment"},
- ],
- }
- )
diff --git a/dify-agent/tests/local/dify_agent/layers/ask_human/test_layer.py b/dify-agent/tests/local/dify_agent/layers/ask_human/test_layer.py
deleted file mode 100644
index 903a3164a01..00000000000
--- a/dify-agent/tests/local/dify_agent/layers/ask_human/test_layer.py
+++ /dev/null
@@ -1,152 +0,0 @@
-import asyncio
-import inspect
-from collections.abc import Awaitable
-from typing import Any, cast
-
-import pytest
-from pydantic_ai.messages import ToolCallPart
-from pydantic_ai.tools import DeferredToolRequests, ToolDefinition
-
-from dify_agent.layers.ask_human import DifyAskHumanLayerConfig
-from dify_agent.layers.ask_human.schema import AskHumanToolArgs
-from dify_agent.layers.ask_human.layer import DifyAskHumanLayer
-
-
-async def _await_tool_definition(value: Awaitable[ToolDefinition | None]) -> ToolDefinition | None:
- return await value
-
-
-def test_ask_human_layer_exposes_one_external_tool_and_prompt_hint() -> None:
- config = DifyAskHumanLayerConfig(
- tool_name="human_gate",
- tool_description="Collect a human decision.",
- max_fields=2,
- max_actions=3,
- allowed_field_types=["paragraph"],
- allow_file_fields=False,
- max_question_chars=240,
- max_markdown_chars=512,
- max_field_label_chars=32,
- max_action_label_chars=16,
- )
- layer = DifyAskHumanLayer.from_config(config)
-
- prompt_hint = layer.build_prompt_hint()
- tool = layer.tools[0]
- prepare = tool.prepare
- assert prepare is not None
- prepared_or_awaitable = prepare(
- cast(Any, None),
- ToolDefinition(
- name=tool.name, description=tool.description, parameters_json_schema=tool.function_schema.json_schema
- ),
- )
- prepared = (
- asyncio.run(_await_tool_definition(cast(Awaitable[ToolDefinition | None], prepared_or_awaitable)))
- if inspect.isawaitable(prepared_or_awaitable)
- else prepared_or_awaitable
- )
-
- assert len(layer.prefix_prompts) == 1
- assert len(layer.tools) == 1
- assert "Allowed field types: paragraph." in prompt_hint
- assert "File upload fields are disabled." in prompt_hint
- assert "Use at most 2 field(s)." in prompt_hint
- assert "Use at most 3 action(s)." in prompt_hint
- assert "Keep 'question' under 240 characters." in prompt_hint
- assert "Keep 'markdown' under 512 characters." in prompt_hint
- assert "Keep each field label under 32 characters." in prompt_hint
- assert "Keep each action label under 16 characters." in prompt_hint
- assert prepared is not None
- assert prepared.name == "human_gate"
- assert prepared.description == "Collect a human decision."
- assert prepared.kind == "external"
- assert prepared.parameters_json_schema == AskHumanToolArgs.model_json_schema()
-
-
-def test_ask_human_layer_normalizes_default_action_in_deferred_payload() -> None:
- layer = DifyAskHumanLayer.from_config(DifyAskHumanLayerConfig())
-
- payload = layer.build_deferred_tool_call_payload(
- DeferredToolRequests(
- calls=[
- ToolCallPart(
- tool_name="ask_human",
- args={
- "question": "Need a human answer",
- "fields": [{"type": "paragraph", "name": "comment", "label": "Comment"}],
- },
- tool_call_id="call-1",
- )
- ]
- )
- )
-
- assert payload.tool_call_id == "call-1"
- assert payload.tool_name == "ask_human"
- assert payload.args == {
- "title": None,
- "question": "Need a human answer",
- "markdown": None,
- "fields": [
- {
- "type": "paragraph",
- "name": "comment",
- "label": "Comment",
- "required": False,
- "placeholder": None,
- "default": None,
- }
- ],
- "actions": [{"id": "submit", "label": "Submit", "style": "primary"}],
- "urgency": "normal",
- }
- assert payload.metadata == {
- "layer_type": "dify.ask_human",
- "tool_name": "ask_human",
- "schema_version": 1,
- }
-
-
-def test_ask_human_layer_rejects_disallowed_field_types_in_deferred_payload() -> None:
- layer = DifyAskHumanLayer.from_config(DifyAskHumanLayerConfig(allowed_field_types=["paragraph"]))
-
- with pytest.raises(ValueError, match="field type 'select' is not allowed"):
- _ = layer.build_deferred_tool_call_payload(
- DeferredToolRequests(
- calls=[
- ToolCallPart(
- tool_name="ask_human",
- args={
- "question": "Need a choice",
- "fields": [
- {
- "type": "select",
- "name": "decision",
- "label": "Decision",
- "options": [{"value": "yes", "label": "Yes"}],
- }
- ],
- },
- tool_call_id="call-2",
- )
- ]
- )
- )
-
-
-def test_ask_human_layer_rejects_tool_name_mismatch_in_deferred_payload() -> None:
- layer = DifyAskHumanLayer.from_config(DifyAskHumanLayerConfig(tool_name="human_gate"))
-
- with pytest.raises(ValueError, match="deferred tool name must be 'human_gate', got 'ask_human'"):
- _ = layer.build_deferred_tool_call_payload(
- DeferredToolRequests(
- calls=[
- ToolCallPart(
- tool_name="ask_human",
- args={"question": "Need a human answer"},
- tool_call_id="call-3",
- )
- ]
- )
- )
diff --git a/dify-agent/tests/local/dify_agent/layers/config/test_layer.py b/dify-agent/tests/local/dify_agent/layers/config/test_layer.py
index c66f0c88a47..1190b861df6 100644
--- a/dify-agent/tests/local/dify_agent/layers/config/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/config/test_layer.py
@@ -1,257 +1,88 @@
-"""Behavior tests for the runtime Dify config layer."""
-
-from __future__ import annotations
+"""Config pre-pulls run inside Shell and persist only completed initialization."""
import json
-from typing import Literal
+import httpx
import pytest
-from dify_agent.layers.config import DifyConfigLayerConfig
-from dify_agent.layers.config.layer import (
- DifyConfigLayer,
- DifyConfigLayerError,
- _AGENT_FILE_UPLOAD_REPLY_HINT,
-)
-from dify_agent.layers.shell import DifyShellLayerConfig
-from dify_agent.layers.shell.layer import CompleteRemoteCommandResult, DifyShellLayer
-
-
-def _shell_layer() -> DifyShellLayer:
- return DifyShellLayer.from_config_with_settings(
- DifyShellLayerConfig(),
- )
-
-
-def _build_layer(*, writable: bool = True) -> DifyConfigLayer:
- layer = DifyConfigLayer.from_config(
- DifyConfigLayerConfig.model_validate(
- {
- "agent_id": "agent-1",
- "config_version": {"id": "cfg-1", "kind": "build_draft", "writable": writable},
- "skills": [{"name": "runtime-skill", "description": "Runtime skill."}],
- "files": [{"name": "runtime-file.txt"}],
- "env_keys": ["RUNTIME_KEY"],
- "note": "Runtime note.",
- "mentioned_skill_names": ["alpha"],
- "mentioned_file_names": ["guide.txt"],
- }
- )
- )
- layer.bind_deps({"shell": _shell_layer()})
- return layer
-
-
-def _remote_result(
- output: str,
- *,
- exit_code: int | None = 0,
- output_complete: bool = True,
- incomplete_reason: Literal["output_limit", "timeout"] | None = None,
-) -> CompleteRemoteCommandResult:
- return CompleteRemoteCommandResult(
- job_id="remote-config-pull",
- status="exited",
- done=True,
- exit_code=exit_code,
- output=output,
- output_complete=output_complete,
- incomplete_reason=incomplete_reason,
- offset=len(output),
- output_path="/tmp/config-pull-output.log",
- )
-
-
-def _skill_pull_output(*names: str, include_skill: bool = True) -> str:
- items = []
- if include_skill:
- items = [
- {
- "name": name,
- "archive_path": f"/workspace/.dify_conf/skills/{name}.zip",
- "directory_path": f"/workspace/.dify_conf/skills/{name}",
- "skill_md": "# Alpha\nUse it.\n",
- }
- for name in names or ("alpha",)
- ]
- return json.dumps({"items": items})
-
-
-def _file_pull_output(*names: str, include_file: bool = True) -> str:
- items = []
- if include_file:
- items = [{"name": name, "path": f"/workspace/.dify_conf/files/{name}"} for name in names or ("guide.txt",)]
- return json.dumps({"items": items})
-
-
-def test_build_shell_pull_scripts_include_targets() -> None:
- layer = _build_layer()
-
- skill_script = layer._build_shell_skill_pull_script(["alpha", "skill with space"])
- file_script = layer._build_shell_file_pull_script(["guide.txt", "file with space.txt"])
-
- assert skill_script == "set -eu\ndify-agent config skills pull --json alpha 'skill with space'"
- assert file_script == "set -eu\ndify-agent config files pull --json guide.txt 'file with space.txt'"
-
-
-async def test_on_context_create_computes_runtime_fields_and_pulls_mentioned_assets_in_batches(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- layer = _build_layer()
- captured_scripts: list[str] = []
- active_commands = 0
- max_active_commands = 0
-
- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):
- nonlocal active_commands, max_active_commands
- del self, timeout
- assert inject_agent_stub_env is True
- assert "--help" not in script
- assert "dify-agent config manifest" not in script
- captured_scripts.append(script)
- active_commands += 1
- max_active_commands = max(max_active_commands, active_commands)
- active_commands -= 1
- if "skills pull" in script:
- return _remote_result(_skill_pull_output())
- if "files pull" in script:
- return _remote_result(_file_pull_output())
- raise AssertionError(f"unexpected script: {script}")
-
- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)
-
- await layer.on_context_create()
-
- assert max_active_commands == 1
- assert len(captured_scripts) == 2
- assert captured_scripts == [
- "set -eu\ndify-agent config skills pull --json alpha",
- "set -eu\ndify-agent config files pull --json guide.txt",
- ]
- assert layer.runtime_state.pulled_skill_outputs == {"alpha": "/workspace/.dify_conf/skills/alpha\n# Alpha\nUse it."}
- assert layer.runtime_state.pulled_file_outputs == {"guide.txt": "/workspace/.dify_conf/files/guide.txt"}
- assert "dify-agent config note push --help" in layer.runtime_state.config_cli_help
- assert "dify-agent file upload --help" in layer.runtime_state.config_cli_help
- assert "dify-agent file public-url --help" in layer.runtime_state.config_cli_help
- assert "dify-agent file download --help" in layer.runtime_state.config_cli_help
- assert layer.runtime_state.push_spec_json_schema == ""
- suffix_prompt = layer.build_suffix_prompt()
- assert suffix_prompt.index("Agent config CLI reference for installed `dify-agent`:") < suffix_prompt.index(
- "Agent file CLI reference for installed `dify-agent`:"
- )
- assert "$ dify-agent file upload --help" in suffix_prompt
- assert "$ dify-agent file public-url --help" in suffix_prompt
- assert "$ dify-agent file download --help" in suffix_prompt
- assert suffix_prompt.index("$ dify-agent file upload --help") < suffix_prompt.index(
- "$ dify-agent file public-url --help"
- )
- assert suffix_prompt.index("$ dify-agent file public-url --help") < suffix_prompt.index(
- "$ dify-agent file download --help"
- )
- assert _AGENT_FILE_UPLOAD_REPLY_HINT in suffix_prompt
+from dify_agent.adapters.shell.protocols import CompleteShellCommandResult
+from dify_agent.layers.config import layer as config_module
+from dify_agent.layers.shell.layer import ShellSession
+from dify_agent.protocol.schemas import RunLayerSpec
+from dify_agent.runtime.context import Services
+from dify_agent.runtime_backend import RuntimeBackendProfile
+from tests.local.dify_agent.runtime.test_runner import Backend, Commands, request, run_runner, runtime_specs
@pytest.mark.anyio
-async def test_on_context_create_batches_all_mentioned_assets_into_two_serial_jobs(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- layer = _build_layer()
- layer.config = layer.config.model_copy(
- update={
- "mentioned_skill_names": [f"skill-{index}" for index in range(4)],
- "mentioned_file_names": [f"file-{index}.txt" for index in range(4)],
- }
- )
- captured_scripts: list[str] = []
-
- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):
- del self, timeout
- assert inject_agent_stub_env is True
- captured_scripts.append(script)
- if "skills pull" in script:
- return _remote_result(_skill_pull_output(*(f"skill-{index}" for index in range(4))))
- return _remote_result(_file_pull_output(*(f"file-{index}.txt" for index in range(4))))
-
- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)
-
- await layer.on_context_create()
-
- assert captured_scripts == [
- "set -eu\ndify-agent config skills pull --json skill-0 skill-1 skill-2 skill-3",
- "set -eu\ndify-agent config files pull --json file-0.txt file-1.txt file-2.txt file-3.txt",
- ]
- assert set(layer.runtime_state.pulled_skill_outputs) == {f"skill-{index}" for index in range(4)}
- assert set(layer.runtime_state.pulled_file_outputs) == {f"file-{index}.txt" for index in range(4)}
-
-
-async def test_on_context_resume_does_not_recompute_or_pull(monkeypatch: pytest.MonkeyPatch) -> None:
- layer = _build_layer()
- layer.runtime_state.config_context_json = "cached"
- layer.runtime_state.config_cli_help = {"cached": "help"}
-
- async def fail_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):
- del self, script, inject_agent_stub_env, timeout
- raise AssertionError("resume must not run config shell commands")
-
- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fail_run_remote_script)
-
- await layer.on_context_resume()
-
- assert layer.runtime_state.config_context_json == "cached"
- assert layer.runtime_state.config_cli_help == {"cached": "help"}
-
-
-async def test_on_context_create_raises_when_shell_output_is_truncated(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- layer = _build_layer()
-
- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):
- del self, inject_agent_stub_env, timeout
- if "skills pull" in script:
- return _remote_result(_skill_pull_output(), output_complete=False, incomplete_reason="output_limit")
- return _remote_result(_file_pull_output())
-
- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)
-
- with pytest.raises(DifyConfigLayerError, match="output was incomplete"):
- await layer.on_context_create()
-
-
-async def test_on_context_create_raises_when_mentioned_skill_is_missing(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- layer = _build_layer()
-
- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):
- del self, inject_agent_stub_env, timeout
- if "skills pull" in script:
- return _remote_result(_skill_pull_output(include_skill=False))
- return _remote_result(_file_pull_output())
-
- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)
-
- with pytest.raises(DifyConfigLayerError, match="missing pull output"):
- await layer.on_context_create()
-
-
-async def test_on_context_create_raises_when_mentioned_file_is_missing(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- layer = _build_layer()
-
- async def fake_run_remote_script(self, script: str, *, inject_agent_stub_env: bool = False, timeout: float = 10.0):
- del self, inject_agent_stub_env, timeout
- if "skills pull" in script:
- return _remote_result(_skill_pull_output())
- return _remote_result(_file_pull_output(include_file=False))
-
- monkeypatch.setattr(DifyShellLayer, "run_remote_script", fake_run_remote_script)
+async def test_first_pull_failure_retries_then_current_config_refreshes_without_repull(monkeypatch):
+ commands = Commands()
+ backend = Backend(commands)
+ pulls = []
+ fail = True
+
+ async def pull(session, script, **kwargs):
+ assert backend.active
+ assert kwargs["inject_agent_stub_env"] is True
+ pulls.append(script)
+ output = (
+ ""
+ if fail
+ else json.dumps(
+ {"items": [{"name": "skill", "directory_path": "/skills/skill", "skill_md": "Instructions from skill"}]}
+ )
+ )
+ return CompleteShellCommandResult("pull", "exited", True, 1 if fail else 0, output, True, None, len(output))
+
+ monkeypatch.setattr(ShellSession, "run_remote_script", pull)
+ seen_instructions = []
+
+ async def stream(messages, info):
+ assert "Instructions from skill" in info.instructions
+ seen_instructions.append(info.instructions)
+ yield "done"
+
+ def spec(note, *, writable=False):
+ return RunLayerSpec(
+ name="config",
+ config={
+ "mentioned_skill_names": ["skill"],
+ "note": note,
+ "config_version": {"kind": "build_draft" if writable else "snapshot", "writable": writable},
+ },
+ )
- with pytest.raises(DifyConfigLayerError, match="missing pull output"):
- await layer.on_context_create()
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))
+ # Config precedes both resources in the submitted list; native ordering owns entry.
+ first, _ = run_runner(request(spec("original"), *runtime_specs()), services, monkeypatch, stream)
+ with pytest.raises(config_module.DifyConfigLayerError):
+ await first.run()
+ assert first.terminal_session_snapshot.layers["config"]["initialized"] is False
+ assert backend.released == 1
+ fail = False
+ second, _ = run_runner(
+ request(spec("original"), *runtime_specs(), snapshot=first.terminal_session_snapshot),
+ services,
+ monkeypatch,
+ stream,
+ run_id="second",
+ )
+ await second.run()
+ assert second.terminal_session_snapshot.layers["config"]["initialized"] is True
+ third, _ = run_runner(
+ request(spec("revised", writable=True), *runtime_specs(), snapshot=second.terminal_session_snapshot),
+ services,
+ monkeypatch,
+ stream,
+ run_id="third",
+ )
+ await third.run()
+ assert len(pulls) == 2
+ assert backend.acquired == backend.released == 3
+ state = third.terminal_session_snapshot.layers["config"]
+ assert "original" in seen_instructions[0] and "revised" in seen_instructions[1]
+ assert "dify-agent config env push --help" not in seen_instructions[0]
+ assert "dify-agent config env push --help" in seen_instructions[1]
+ assert set(state) == {"initialized", "pulled_skill_outputs", "pulled_file_outputs"}
+ assert "Instructions from skill" in state["pulled_skill_outputs"]["skill"]
diff --git a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py
index 8e795112853..42451428021 100644
--- a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py
+++ b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_configs.py
@@ -1,62 +1,32 @@
import pytest
from pydantic import ValidationError
-
import dify_agent.layers.dify_core_tools as dify_core_tools_exports
from dify_agent.layers.dify_core_tools import DifyCoreToolConfig, DifyCoreToolsLayerConfig
def test_dify_core_tools_package_exports_client_safe_config_symbols_only() -> None:
assert dify_core_tools_exports.__all__ == [
- "DIFY_CORE_TOOLS_LAYER_TYPE_ID",
"DifyCoreToolConfig",
"DifyCoreToolProviderType",
"DifyCoreToolsLayerConfig",
]
- assert dify_core_tools_exports.DIFY_CORE_TOOLS_LAYER_TYPE_ID == "dify.core.tools"
def test_dify_core_tools_layer_config_accepts_supported_provider_types() -> None:
config = DifyCoreToolsLayerConfig.model_validate(
{
"tools": [
- {
- "provider_type": "plugin",
- "provider_id": "langgenius/search/search",
- "tool_name": "search",
- },
- {
- "provider_type": "builtin",
- "provider_id": "audio",
- "tool_name": "transcribe",
- },
- {
- "provider_type": "api",
- "provider_id": "weather",
- "tool_name": "forecast",
- },
- {
- "provider_type": "workflow",
- "provider_id": "workflow-tool",
- "tool_name": "run_workflow",
- },
- {
- "provider_type": "mcp",
- "provider_id": "server-1",
- "tool_name": "search_docs",
- },
+ {"provider_type": "plugin", "provider_id": "langgenius/search/search", "tool_name": "search"},
+ {"provider_type": "builtin", "provider_id": "audio", "tool_name": "transcribe"},
+ {"provider_type": "api", "provider_id": "weather", "tool_name": "forecast"},
+ {"provider_type": "workflow", "provider_id": "workflow-tool", "tool_name": "run_workflow"},
+ {"provider_type": "mcp", "provider_id": "server-1", "tool_name": "search_docs"},
]
}
)
-
assert [tool.provider_type for tool in config.tools] == ["plugin", "builtin", "api", "workflow", "mcp"]
def test_dify_core_tool_config_rejects_unsupported_provider_types() -> None:
with pytest.raises(ValidationError, match="provider_type"):
- _ = DifyCoreToolConfig.model_validate(
- {
- "provider_type": "app",
- "provider_id": "app-tool",
- "tool_name": "run",
- }
- )
+ _ = DifyCoreToolConfig.model_validate({"provider_type": "app", "provider_id": "app-tool", "tool_name": "run"})
diff --git a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py
index f5813c0f7f8..2fe15eb5f03 100644
--- a/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/dify_core_tools/test_layer.py
@@ -1,290 +1,88 @@
-import asyncio
-import sys
-import types
+"""Core tools retain their prepared schemas and API-owned credentials."""
+
+import json
import httpx
import pytest
-from agenton.compositor import Compositor, LayerNode, LayerProvider
-
-
-def _install_graphon_stubs() -> None:
- if "graphon.model_runtime.entities.llm_entities" in sys.modules:
- return
-
- graphon_module = types.ModuleType("graphon")
- model_runtime_module = types.ModuleType("graphon.model_runtime")
- entities_module = types.ModuleType("graphon.model_runtime.entities")
- llm_entities_module = types.ModuleType("graphon.model_runtime.entities.llm_entities")
- message_entities_module = types.ModuleType("graphon.model_runtime.entities.message_entities")
-
- setattr(llm_entities_module, "LLMResultChunk", type("LLMResultChunk", (), {}))
- setattr(llm_entities_module, "LLMUsage", type("LLMUsage", (), {}))
-
- for name in (
- "AssistantPromptMessage",
- "AudioPromptMessageContent",
- "DocumentPromptMessageContent",
- "ImagePromptMessageContent",
- "PromptMessage",
- "PromptMessageContentUnionTypes",
- "PromptMessageTool",
- "SystemPromptMessage",
- "TextPromptMessageContent",
- "ToolPromptMessage",
- "UserPromptMessage",
- "VideoPromptMessageContent",
- ):
- setattr(message_entities_module, name, type(name, (), {}))
-
- sys.modules["graphon"] = graphon_module
- sys.modules["graphon.model_runtime"] = model_runtime_module
- sys.modules["graphon.model_runtime.entities"] = entities_module
- sys.modules["graphon.model_runtime.entities.llm_entities"] = llm_entities_module
- sys.modules["graphon.model_runtime.entities.message_entities"] = message_entities_module
-
- setattr(graphon_module, "model_runtime", model_runtime_module)
- setattr(model_runtime_module, "entities", entities_module)
- setattr(entities_module, "llm_entities", llm_entities_module)
- setattr(entities_module, "message_entities", message_entities_module)
-
-
-_install_graphon_stubs()
-
-from dify_agent.layers.dify_core_tools.configs import DifyCoreToolConfig, DifyCoreToolsLayerConfig # noqa: E402
-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer # noqa: E402
-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig # noqa: E402
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer # noqa: E402
-
-
-def _execution_context_provider() -> LayerProvider[DifyExecutionContextLayer]:
- return LayerProvider.from_factory(
- layer_type=DifyExecutionContextLayer,
- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(
- DifyExecutionContextLayerConfig.model_validate(config),
- daemon_url="http://plugin-daemon",
- daemon_api_key="daemon-secret",
- ),
- )
-
-
-def _core_tools_provider() -> LayerProvider[DifyCoreToolsLayer]:
- return LayerProvider.from_factory(
- layer_type=DifyCoreToolsLayer,
- create=lambda config: DifyCoreToolsLayer.from_config_with_settings(
- DifyCoreToolsLayerConfig.model_validate(config),
- inner_api_url="http://dify-api",
- inner_api_key="inner-secret",
- ),
- )
-
-
-def _execution_context_config() -> DifyExecutionContextLayerConfig:
- return DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- app_id="app-1",
- workflow_id="workflow-1",
- workflow_run_id="workflow-run-1",
- node_id="node-1",
- node_execution_id="node-exec-1",
- conversation_id="conversation-1",
- agent_id="agent-1",
- agent_config_version_id="snapshot-1",
- agent_mode="workflow_run",
- invoke_from="service-api",
- )
-
-
-def test_core_tools_layer_exposes_pydantic_ai_tool_and_returns_inner_api_observation() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(
- transport=httpx.MockTransport(
- lambda _request: httpx.Response(
- 200,
- json={
- "messages": [{"type": "text", "message": {"text": "done"}}],
- "observation": "done",
- "metadata": {"provider_type": "builtin"},
- },
- )
- )
- ) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "core_tools": DifyCoreToolsLayerConfig(
- tools=[
- DifyCoreToolConfig(
- provider_type="builtin",
- provider_id="audio",
- tool_name="transcribe",
- name="transcribe",
- description="Transcribe audio.",
- parameters=[],
- parameters_json_schema={"type": "object", "properties": {}, "required": []},
- )
- ]
- ),
- }
- ) as run:
- layer = run.get_layer("core_tools", DifyCoreToolsLayer)
- tool = (await layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]
- assert result == "done"
-
- asyncio.run(scenario())
+from dify_agent.layers.dify_core_tools.layer import Config, Toolset
+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
+from dify_agent.runtime.context import Deps, Services
+from tests.local.dify_agent.module_support import invoke_native_tool
@pytest.mark.parametrize(
- ("response", "expected"),
+ "status,body,expected",
[
+ (200, {"observation": "completed", "messages": [], "metadata": {}}, "completed"),
+ (429, {"code": "rate_limit", "message": "busy"}, "temporarily unavailable"),
+ (404, {"code": "app_not_found", "message": "missing"}, "app context no longer exists"),
+ (403, {"code": "app_tenant_mismatch", "message": "invalid"}, "app context is invalid"),
+ (422, {"code": "agent_tool_credential_invalid", "message": "invalid"}, "check your tool provider credentials"),
(
- httpx.Response(404, json={"code": "app_not_found", "message": "App not found."}),
- "Tool is unavailable because its app context no longer exists.",
- ),
- (
- httpx.Response(403, json={"code": "app_tenant_mismatch", "message": "App does not belong to tenant."}),
- "Tool is unavailable because its app context is invalid.",
- ),
- (
- httpx.Response(404, json={"code": "agent_tool_declaration_not_found", "message": "tool missing"}),
+ 404,
+ {"code": "agent_tool_declaration_not_found", "message": "missing"},
"there is not a tool named transcribe",
),
(
- httpx.Response(
- 422,
- json={"code": "agent_tool_credential_invalid", "message": "credential region is required"},
- ),
- "Please check your tool provider credentials",
- ),
- (
- httpx.Response(422, json={"code": "tool_parameters_invalid", "message": "query is required"}),
- "tool parameters validation error: query is required, please check your tool parameters",
- ),
- (
- httpx.Response(422, json={"code": "agent_tool_invoke_failed", "message": "workflow crashed"}),
- "tool invoke error: workflow crashed",
+ 422,
+ {"code": "tool_parameters_invalid", "message": "query required"},
+ "tool parameters validation error: query required",
),
],
)
-def test_core_tools_layer_maps_specific_inner_api_error_codes_to_observations(
- response: httpx.Response,
- expected: str,
-) -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: response)) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "core_tools": DifyCoreToolsLayerConfig(
- tools=[
- DifyCoreToolConfig(
- provider_type="builtin",
- provider_id="audio",
- tool_name="transcribe",
- name="transcribe",
- description="Transcribe audio.",
- parameters=[],
- parameters_json_schema={"type": "object", "properties": {}, "required": []},
- )
- ]
- ),
- }
- ) as run:
- layer = run.get_layer("core_tools", DifyCoreToolsLayer)
- tool = (await layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]
- assert result == expected
-
- asyncio.run(scenario())
-
-
-def test_core_tools_layer_reports_missing_execution_context_without_parameter_validation_text() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),
- ]
+async def test_native_tool_preserves_schema_invocation_and_observations(status, body, expected):
+ schema = {"type": "object", "properties": {"source": {"type": "string"}}, "required": ["source"]}
+ config = Config(
+ tools=[
+ {
+ "provider_type": "builtin",
+ "provider_id": "audio",
+ "tool_name": "transcribe",
+ "credential_id": "credential",
+ "runtime_parameters": {"region": "hidden"},
+ "parameters_json_schema": schema,
+ }
+ ]
+ )
+ identity = DifyExecutionContextLayerConfig(
+ tenant_id="tenant",
+ user_id="user",
+ user_from="account",
+ app_id="app",
+ agent_mode="agent_app",
+ invoke_from="web-app",
+ )
+ sent = []
+
+ def handler(request):
+ assert request.url.path == "/inner/api/agent/tools/invoke"
+ assert request.headers["X-Inner-Api-Key"] == "secret"
+ sent.append(json.loads(request.content))
+ return httpx.Response(status, json=body)
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ deps = Deps(
+ layers={
+ "core_tools": {"config": config.model_dump(mode="json"), "state": {}},
+ "execution_context": {"config": identity.model_dump(mode="json"), "state": {}},
+ },
+ services=Services(client, client, inner_api_key="secret"),
+ run_id="test",
)
- async with httpx.AsyncClient(
- transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={"observation": "unused"}))
- ) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config().model_copy(update={"app_id": None}),
- "core_tools": DifyCoreToolsLayerConfig(
- tools=[
- DifyCoreToolConfig(
- provider_type="builtin",
- provider_id="audio",
- tool_name="transcribe",
- name="transcribe",
- description="Transcribe audio.",
- parameters=[],
- parameters_json_schema={"type": "object", "properties": {}, "required": []},
- )
- ]
- ),
- }
- ) as run:
- layer = run.get_layer("core_tools", DifyCoreToolsLayer)
- tool = (await layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]
- assert result == "Tool is unavailable because required execution context is missing."
-
- asyncio.run(scenario())
+ def inspect(info):
+ tool = info.function_tools[0]
+ assert tool.name == "transcribe"
+ assert tool.parameters_json_schema == schema
+ assert tool.strict is False
- "response", [httpx.Response(429, json={"code": "knowledge_rate_limited"}), httpx.Response(502)]
-)
-def test_core_tools_layer_converts_retryable_failures_to_temporary_unavailable_observation(
- response: httpx.Response,
-) -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("core_tools", _core_tools_provider(), deps={"execution_context": "execution_context"}),
- ]
+ result = await invoke_native_tool(
+ deps, Toolset("core_tools"), "transcribe", {"source": "audio.mp3"}, inspect=inspect
)
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: response)) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "core_tools": DifyCoreToolsLayerConfig(
- tools=[
- DifyCoreToolConfig(
- provider_type="builtin",
- provider_id="audio",
- tool_name="transcribe",
- name="transcribe",
- description="Transcribe audio.",
- parameters=[],
- parameters_json_schema={"type": "object", "properties": {}, "required": []},
- )
- ]
- ),
- }
- ) as run:
- layer = run.get_layer("core_tools", DifyCoreToolsLayer)
- tool = (await layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call({}, None) # pyright: ignore[reportArgumentType]
- assert result == "Tool is temporarily unavailable. Please continue without it if possible."
-
- asyncio.run(scenario())
+ assert expected in result.output
+ assert sent[0]["caller"]["tenant_id"] == "tenant"
+ assert sent[0]["tool"]["runtime_parameters"] == {"region": "hidden"}
+ assert sent[0]["tool"]["tool_parameters"] == {"source": "audio.mp3"}
+ assert not client.is_closed
diff --git a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py
index 2f9f6880564..d10001c02b4 100644
--- a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py
+++ b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_configs.py
@@ -1,8 +1,6 @@
from types import SimpleNamespace
-
import pytest
from pydantic import ValidationError
-
import dify_agent.layers.dify_plugin as dify_plugin_exports
from dify_agent.layers.dify_plugin import (
DifyPluginLLMLayerConfig,
@@ -18,8 +16,6 @@ from dify_agent.layers.dify_plugin import (
def test_dify_plugin_package_exports_client_safe_config_symbols_only() -> None:
assert dify_plugin_exports.__all__ == [
- "DIFY_PLUGIN_LLM_LAYER_TYPE_ID",
- "DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID",
"DifyPluginCredentialValue",
"DifyPluginLLMLayerConfig",
"DifyPluginToolCredentialType",
@@ -31,8 +27,6 @@ def test_dify_plugin_package_exports_client_safe_config_symbols_only() -> None:
"DifyPluginToolsLayerConfig",
"DifyPluginToolValue",
]
- assert dify_plugin_exports.DIFY_PLUGIN_LLM_LAYER_TYPE_ID == "dify.plugin.llm"
- assert dify_plugin_exports.DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID == "dify.plugin.tools"
assert not hasattr(dify_plugin_exports, "DifyPluginLLMLayer")
@@ -44,36 +38,28 @@ def test_dify_plugin_llm_config_discards_legacy_credentials() -> None:
"model": "gpt-4o-mini",
"credentials": {"api_key": "secret", "nested": {"legacy": True}},
"model_settings": {"temperature": 0.2, "max_tokens": 64},
- "context_window_tokens": 128_000,
+ "context_window_tokens": 128000,
}
)
-
assert config.plugin_id == "langgenius/openai"
assert config.model_provider == "openai"
assert not hasattr(config, "credentials")
assert "credentials" not in config.model_dump(mode="json")
assert config.model_settings == {"temperature": 0.2, "max_tokens": 64}
- assert config.context_window_tokens == 128_000
+ assert config.context_window_tokens == 128000
def test_dify_plugin_llm_config_rejects_old_provider_field() -> None:
with pytest.raises(ValidationError):
_ = DifyPluginLLMLayerConfig.model_validate(
- {
- "provider": "openai",
- "plugin_id": "langgenius/openai",
- "model": "gpt-4o-mini",
- }
+ {"provider": "openai", "plugin_id": "langgenius/openai", "model": "gpt-4o-mini"}
)
def test_dify_plugin_llm_config_rejects_non_positive_context_window() -> None:
with pytest.raises(ValidationError):
_ = DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="gpt-4o-mini",
- context_window_tokens=0,
+ plugin_id="langgenius/openai", model_provider="openai", model="gpt-4o-mini", context_window_tokens=0
)
@@ -102,15 +88,12 @@ def test_dify_plugin_tools_layer_config_accepts_prepared_parameters_and_schema()
],
parameters_json_schema={
"type": "object",
- "properties": {
- "query": {"type": "string", "description": "Search query"},
- },
+ "properties": {"query": {"type": "string", "description": "Search query"}},
"required": ["query"],
},
)
]
)
-
assert config.tools[0].plugin_id == "langgenius/tools"
assert config.tools[0].provider == "search"
assert config.tools[0].tool_name == "web_search"
@@ -134,15 +117,9 @@ def test_dify_plugin_tool_parameter_accepts_api_tool_parameter_dump_shape() -> N
"default": "dify",
"llm_description": "Search query",
"input_schema": {"type": "string"},
- "options": [
- {
- "value": "dify",
- "label": {"en_US": "Dify"},
- }
- ],
+ "options": [{"value": "dify", "label": {"en_US": "Dify"}}],
}
)
-
assert parameter.name == "query"
assert parameter.type is DifyPluginToolParameterType.SELECT
assert parameter.form is DifyPluginToolParameterForm.LLM
@@ -166,7 +143,6 @@ def test_dify_plugin_tool_parameter_accepts_api_tool_parameter_attributes() -> N
options=[SimpleNamespace(value="en", label=SimpleNamespace(en_US="English"))],
)
)
-
assert parameter.name == "language"
assert parameter.type is DifyPluginToolParameterType.STRING
assert parameter.form is DifyPluginToolParameterForm.FORM
@@ -216,9 +192,5 @@ def test_dify_plugin_tool_config_rejects_strict_flag() -> None:
def test_dify_plugin_tool_config_requires_explicit_credential_type() -> None:
with pytest.raises(ValidationError):
_ = DifyPluginToolConfig.model_validate(
- {
- "plugin_id": "langgenius/tools",
- "provider": "search",
- "tool_name": "web_search",
- }
+ {"plugin_id": "langgenius/tools", "provider": "search", "tool_name": "web_search"}
)
diff --git a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py
index a47efd75437..4d089ed7a07 100644
--- a/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py
+++ b/dify-agent/tests/local/dify_agent/layers/dify_plugin/test_layers.py
@@ -1,1047 +1,160 @@
-import asyncio
+"""Plugin tools use JSON identity, prepared schemas and native dispatch."""
+
import json
-from types import SimpleNamespace
import httpx
import pytest
-from pydantic import JsonValue
-from agenton.compositor import Compositor, LayerNode, LayerProvider
-from dify_agent.adapters.llm import DifyLLMAdapterModel
-from dify_agent.layers.dify_plugin.configs import (
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- DifyPluginLLMLayerConfig,
- DifyPluginToolConfig,
- DifyPluginToolOption,
- DifyPluginToolParameter,
- DifyPluginToolParameterForm,
- DifyPluginToolParameterType,
- DifyPluginToolsLayerConfig,
-)
-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer
-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer, _PluginToolFileContext
-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
+from dify_agent.layers.dify_plugin import tools_layer
+from dify_agent.layers.dify_plugin.llm_layer import Capability as ModelCapability, Config as ModelConfig
+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
+from dify_agent.runtime.context import Deps, Services
+from tests.local.dify_agent.module_support import invoke_native_tool
-def _execution_context_config() -> DifyExecutionContextLayerConfig:
+def identity():
return DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
+ tenant_id="tenant",
+ user_id="user",
user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- )
-
-
-def _llm_config() -> DifyPluginLLMLayerConfig:
- return DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- model_settings={"temperature": 0.2},
- )
-
-
-def _tools_config() -> DifyPluginToolsLayerConfig:
- return DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- description="Search the web.",
- runtime_parameters={"api_version": "2026-01", "auth_scope": "workspace"},
- parameters=_prepared_tool_parameters(),
- parameters_json_schema=_prepared_tool_schema(),
- )
- ]
+ app_id="app",
+ agent_mode="agent_app",
+ invoke_from="web-app",
)
-def _missing_hidden_parameter_tools_config() -> DifyPluginToolsLayerConfig:
- return DifyPluginToolsLayerConfig(
+async def test_native_plugin_tool_prepares_schema_merges_hidden_parameters_and_decodes_stream():
+ schema = {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}
+ config = tools_layer.Config(
tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- description="Search the web.",
- runtime_parameters={"api_version": "2026-01"},
- parameters=_prepared_tool_parameters(),
- parameters_json_schema=_prepared_tool_schema(),
- )
+ {
+ "plugin_id": "langgenius/search",
+ "provider": "search",
+ "tool_name": "web_search",
+ "name": "search",
+ "credential_type": "api-key",
+ "credentials": {"api_key": "tool-secret"},
+ "runtime_parameters": {"scope": "workspace"},
+ "parameters_json_schema": schema,
+ "parameters": [
+ {"name": "query", "type": "string", "form": "llm", "required": True},
+ {"name": "scope", "type": "string", "form": "form", "required": True},
+ {"name": "region", "type": "string", "form": "form", "default": "global"},
+ ],
+ }
]
)
-
-
-def _execution_context_provider() -> LayerProvider[DifyExecutionContextLayer]:
- return LayerProvider.from_factory(
- layer_type=DifyExecutionContextLayer,
- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(
- DifyExecutionContextLayerConfig.model_validate(config),
- daemon_url="http://plugin-daemon",
- daemon_api_key="daemon-secret",
- ),
- )
-
-
-def _tools_provider() -> LayerProvider[DifyPluginToolsLayer]:
- return LayerProvider.from_factory(
- layer_type=DifyPluginToolsLayer,
- create=lambda config: DifyPluginToolsLayer.from_config_with_settings(
- DifyPluginToolsLayerConfig.model_validate(config),
- inner_api_url="http://dify-api",
- inner_api_key="inner-secret",
- ),
- )
-
-
-def _prepared_tool_parameters() -> list[DifyPluginToolParameter]:
- return [
- DifyPluginToolParameter(
- name="query",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Search query",
- ),
- DifyPluginToolParameter(
- name="region",
- type=DifyPluginToolParameterType.SELECT,
- form=DifyPluginToolParameterForm.LLM,
- required=False,
- llm_description="Search region",
- options=[DifyPluginToolOption(value="global"), DifyPluginToolOption(value="cn")],
- ),
- DifyPluginToolParameter(
- name="api_version",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.FORM,
- required=True,
- llm_description="Hidden API version",
- ),
- DifyPluginToolParameter(
- name="auth_scope",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.FORM,
- required=True,
- llm_description="Hidden auth scope",
- ),
- ]
-
-
-def _prepared_tool_schema() -> dict[str, JsonValue]:
- return {
- "type": "object",
- "properties": {
- "query": {"type": "string", "description": "Search query"},
- "region": {
- "type": "string",
- "description": "Search region",
- "enum": ["global", "cn"],
+ seen = []
+
+ def handler(request):
+ assert request.url.path == "/plugin/tenant/dispatch/tool/invoke"
+ assert request.headers["X-Plugin-ID"] == "langgenius/search"
+ assert request.headers["X-Api-Key"] == "daemon-secret"
+ seen.append(json.loads(request.content))
+ return httpx.Response(
+ 200,
+ text="data: "
+ + json.dumps({"code": 0, "message": "ok", "data": {"type": "text", "message": {"text": "found"}}})
+ + "\n",
+ )
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ deps = Deps(
+ layers={
+ "tools": {"config": config.model_dump(mode="json"), "state": {}},
+ "execution_context": {"config": identity().model_dump(mode="json"), "state": {}},
},
- },
- "required": ["query"],
- }
-
-
-def _llm_only_parameter(*, name: str, description: str, default: JsonValue = None) -> DifyPluginToolParameter:
- return DifyPluginToolParameter(
- name=name,
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.LLM,
- required=default is None,
- default=default,
- llm_description=description,
- )
+ services=Services(client, client, plugin_daemon_api_key="daemon-secret"),
+ run_id="test",
+ )
+ def inspect(info):
+ assert info.function_tools[0].name == "search"
+ assert info.function_tools[0].parameters_json_schema == schema
-def _file_parameter(
- *,
- name: str = "source",
- parameter_type: DifyPluginToolParameterType = DifyPluginToolParameterType.FILE,
-) -> DifyPluginToolParameter:
- return DifyPluginToolParameter(
- name=name,
- type=parameter_type,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Source file",
- )
+ result = await invoke_native_tool(
+ deps, tools_layer.Toolset("tools"), "search", {"query": "dify"}, inspect=inspect
+ )
+ assert result.output == "found"
+ assert seen[0]["user_id"] == "user"
+ assert seen[0]["data"]["tool_parameters"] == {"query": "dify", "scope": "workspace", "region": "global"}
+ assert not client.is_closed
-def _file_tools_config(
- *,
- parameter_type: DifyPluginToolParameterType = DifyPluginToolParameterType.FILE,
-) -> DifyPluginToolsLayerConfig:
- return DifyPluginToolsLayerConfig(
+ "value,download",
+ [
+ ({"transfer_method": "tool_file", "reference": "dify-file-ref:file-1"}, True),
+ ("https://example.com/file.pdf", False),
+ ],
+)
+async def test_native_plugin_tool_converts_file_inputs(value, download):
+ config = tools_layer.Config(
tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="read_file",
- credential_type="api-key",
- parameters=[_file_parameter(parameter_type=parameter_type)],
- parameters_json_schema={
- "type": "object",
- "properties": {"source": {"type": "string"}},
- "required": ["source"],
- },
- )
- ]
- )
-
-
-def _invoke_stream_response(
- *,
- error_payload: dict[str, object] | None = None,
- chunked_blob: bool = False,
-) -> httpx.Response:
- if error_payload is not None:
- return httpx.Response(400, json=error_payload)
-
- if chunked_blob:
- stream_payload = "\n".join(
- [
- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'blob_chunk', 'message': {'id': 'blob-1', 'sequence': 0, 'total_length': 11, 'blob': 'aGVsbG8g', 'end': False}}})}",
- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'blob_chunk', 'message': {'id': 'blob-1', 'sequence': 1, 'total_length': 11, 'blob': 'd29ybGQ=', 'end': True}}})}",
- "",
- ]
- )
- return httpx.Response(200, text=stream_payload)
-
- stream_payload = "\n".join(
- [
- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'text', 'message': {'text': 'found '}}})}",
- f"data: {json.dumps({'code': 0, 'message': 'ok', 'data': {'type': 'json', 'message': {'json_object': {'count': 1}}}})}",
- "",
+ {
+ "plugin_id": "files",
+ "provider": "file",
+ "tool_name": "read",
+ "credential_type": "unauthorized",
+ "parameters": [{"name": "source", "type": "file", "form": "llm", "required": True}],
+ "parameters_json_schema": {"type": "object", "properties": {"source": {}}, "required": ["source"]},
+ }
]
)
- return httpx.Response(200, text=stream_payload)
+ sent = []
-
-def _tool_transport(
- *,
- invoke_error_payload: dict[str, object] | None = None,
- chunked_blob: bool = False,
-) -> httpx.MockTransport:
- def handler(request: httpx.Request) -> httpx.Response:
- if request.url.path.endswith("/dispatch/tool/invoke"):
- payload = json.loads(request.content.decode("utf-8"))
- assert payload["user_id"] == "user-1"
- assert payload["data"]["provider"] == "search"
- assert payload["data"]["tool"] == "web_search"
- assert payload["data"]["credential_type"] == "api-key"
- assert payload["data"]["tool_parameters"] == {
- "query": "dify",
- "region": "global",
- "api_version": "2026-01",
- "auth_scope": "workspace",
- }
- return _invoke_stream_response(error_payload=invoke_error_payload, chunked_blob=chunked_blob)
-
- raise AssertionError(f"Unexpected request path: {request.url.path}")
-
- return httpx.MockTransport(handler)
-
-
-def _file_tool_transport(
- *,
- expected_source: object,
- download_response: dict[str, object] | None = None,
-) -> httpx.MockTransport:
- def handler(request: httpx.Request) -> httpx.Response:
- if request.url.path.endswith("/inner/api/download/file/request"):
- assert download_response is not None
- payload = json.loads(request.content.decode("utf-8"))
+ def handler(request):
+ payload = json.loads(request.content)
+ if request.url.path.endswith("/download/file/request"):
+ assert download
assert payload["file"] == {"transfer_method": "tool_file", "reference": "dify-file-ref:file-1"}
- return httpx.Response(200, json={"data": download_response})
-
- if request.url.path.endswith("/dispatch/tool/invoke"):
- payload = json.loads(request.content.decode("utf-8"))
- assert payload["data"]["tool_parameters"]["source"] == expected_source
- return _invoke_stream_response()
-
- raise AssertionError(f"Unexpected request path: {request.url.path}")
-
- return httpx.MockTransport(handler)
-
-
-def test_dify_plugin_type_id_constants_match_implementation_classes() -> None:
- assert DIFY_PLUGIN_LLM_LAYER_TYPE_ID == DifyPluginLLMLayer.type_id
- assert DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID == DifyPluginToolsLayer.type_id
-
-
-def test_dify_plugin_llm_layer_builds_adapter_model_from_direct_dependency() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("renamed-execution-context", _execution_context_provider()),
- LayerNode("llm", DifyPluginLLMLayer, deps={"execution_context": "renamed-execution-context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(200))) as client:
- async with compositor.enter(
- configs={
- "renamed-execution-context": _execution_context_config(),
- "llm": _llm_config(),
- }
- ) as run:
- execution_context = run.get_layer("renamed-execution-context", DifyExecutionContextLayer)
- llm = run.get_layer("llm", DifyPluginLLMLayer)
-
- model = llm.get_model(http_client=client, agent_run_id="00000000-0000-0000-0000-000000000001")
-
- assert llm.deps.execution_context is execution_context
- assert isinstance(model, DifyLLMAdapterModel)
- assert model.model_name == "demo-model"
- assert model.model_provider == "openai"
- assert not hasattr(model, "credentials")
- assert model.provider.name == "DifyAPI/langgenius/openai"
- assert model.provider.client.http_client is client
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_uses_prepared_tool_definition_and_invokes_daemon() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=_tool_transport()) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}
- ) as run:
- tools_layer = run.get_layer("tools", DifyPluginToolsLayer)
- tool = (await tools_layer.get_tools(http_client=client, dify_api_http_client=client))[0]
-
- tool_def = await tool.prepare_tool_def(None) # pyright: ignore[reportArgumentType]
- result = await tool.function_schema.call(
- {"query": "dify", "region": "global"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert tool.name == "web_search"
- assert tool.description == "Search the web."
- assert tool_def is not None
- assert tool_def.parameters_json_schema == _prepared_tool_schema()
- assert tool_def.strict is False
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_uses_each_tool_plugin_id_for_transport() -> None:
- async def scenario() -> None:
- seen_requests: list[tuple[str, str, str, str]] = []
-
- def handler(request: httpx.Request) -> httpx.Response:
- if request.url.path.endswith("/dispatch/tool/invoke"):
- payload = json.loads(request.content.decode("utf-8"))
- seen_requests.append(
- (
- request.headers["X-Plugin-ID"],
- payload["user_id"],
- payload["data"]["provider"],
- payload["data"]["tool"],
- )
- )
- return _invoke_stream_response()
-
- raise AssertionError(f"Unexpected request path: {request.url.path}")
-
- tools_config = DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools-a",
- provider="search-a",
- tool_name="web_search_a",
- credential_type="api-key",
- parameters=[_llm_only_parameter(name="query", description="Search query A")],
- parameters_json_schema={
- "type": "object",
- "properties": {"query": {"type": "string", "description": "Search query A"}},
- "required": ["query"],
- },
- ),
- DifyPluginToolConfig(
- plugin_id="langgenius/tools-b",
- provider="search-b",
- tool_name="web_search_b",
- credential_type="api-key",
- parameters=[_llm_only_parameter(name="query", description="Search query B")],
- parameters_json_schema={
- "type": "object",
- "properties": {"query": {"type": "string", "description": "Search query B"}},
- "required": ["query"],
- },
- ),
- ]
- )
-
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": tools_config}
- ) as run:
- tools = await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
-
- await tools[0].function_schema.call({"query": "first"}, None) # pyright: ignore[reportArgumentType]
- await tools[1].function_schema.call({"query": "second"}, None) # pyright: ignore[reportArgumentType]
-
- assert seen_requests == [
- ("langgenius/tools-a", "user-1", "search-a", "web_search_a"),
- ("langgenius/tools-b", "user-1", "search-b", "web_search_b"),
- ]
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_casts_prepared_parameter_values_before_invocation() -> None:
- async def scenario() -> None:
- def handler(request: httpx.Request) -> httpx.Response:
- if request.url.path.endswith("/dispatch/tool/invoke"):
- payload = json.loads(request.content.decode("utf-8"))
- assert payload["user_id"] == "user-1"
- assert payload["data"]["tool_parameters"] == {
- "enabled": True,
- "count": 7,
- "tags": ["a", "b"],
- "metadata": {"source": "docs"},
- "model": {"provider": "openai", "model": "gpt-4o-mini"},
- }
- return _invoke_stream_response()
-
- raise AssertionError(f"Unexpected request path: {request.url.path}")
-
- tools_config = DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=[
- DifyPluginToolParameter(
- name="enabled",
- type=DifyPluginToolParameterType.BOOLEAN,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Enable search",
- ),
- DifyPluginToolParameter(
- name="count",
- type=DifyPluginToolParameterType.NUMBER,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Result count",
- ),
- DifyPluginToolParameter(
- name="tags",
- type=DifyPluginToolParameterType.ARRAY,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Tags",
- input_schema={"type": "array", "items": {"type": "string"}},
- ),
- DifyPluginToolParameter(
- name="metadata",
- type=DifyPluginToolParameterType.OBJECT,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Metadata",
- input_schema={"type": "object", "additionalProperties": True},
- ),
- DifyPluginToolParameter(
- name="model",
- type=DifyPluginToolParameterType.MODEL_SELECTOR,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Model selector",
- input_schema={"type": "object", "additionalProperties": True},
- ),
- ],
- parameters_json_schema={
- "type": "object",
- "properties": {
- "enabled": {"type": "boolean", "description": "Enable search"},
- "count": {"type": "number", "description": "Result count"},
- "tags": {"type": "array", "items": {"type": "string"}, "description": "Tags"},
- "metadata": {
- "type": "object",
- "additionalProperties": True,
- "description": "Metadata",
- },
- "model": {
- "type": "object",
- "additionalProperties": True,
- "description": "Model selector",
- },
- },
- "required": ["enabled", "count", "tags", "metadata", "model"],
- },
- )
- ]
- )
-
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": tools_config}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
- )[0]
-
- result = await tool.function_schema.call(
- {
- "enabled": "yes",
- "count": "7",
- "tags": '["a", "b"]',
- "metadata": '{"source": "docs"}',
- "model": {"provider": "openai", "model": "gpt-4o-mini"},
- },
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_sends_prepared_parameter_defaults_to_daemon() -> None:
- async def scenario() -> None:
- def handler(request: httpx.Request) -> httpx.Response:
- if request.url.path.endswith("/dispatch/tool/invoke"):
- payload = json.loads(request.content.decode("utf-8"))
- assert payload["data"]["tool_parameters"] == {
- "query": "dify",
- "region": "global",
- }
- return _invoke_stream_response()
-
- raise AssertionError(f"Unexpected request path: {request.url.path}")
-
- tools_config = DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=[
- _llm_only_parameter(name="query", description="Search query"),
- _llm_only_parameter(name="region", description="Search region", default="global"),
- ],
- parameters_json_schema={
- "type": "object",
- "properties": {
- "query": {"type": "string", "description": "Search query"},
- "region": {"type": "string", "description": "Search region"},
- },
- "required": ["query"],
- },
- )
- ]
- )
-
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": tools_config}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
- )[0]
-
- result = await tool.function_schema.call(
- {"query": "dify"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_converts_remote_url_file_string() -> None:
- async def scenario() -> None:
- expected_source = {
- "dify_model_identity": "__dify__file__",
- "type": "custom",
- "url": "https://example.com/report.pdf",
- "filename": "report.pdf",
- "mime_type": "application/pdf",
- "extension": ".pdf",
- "size": -1,
- }
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=_file_tool_transport(expected_source=expected_source)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client,
- dify_api_http_client=client,
- )
- )[0]
- result = await tool.function_schema.call(
- {"source": "https://example.com/report.pdf"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_converts_remote_url_file_mapping() -> None:
- async def scenario() -> None:
- expected_source = {
- "dify_model_identity": "__dify__file__",
- "type": "custom",
- "url": "https://example.com/report.pdf",
- "filename": "report.pdf",
- "mime_type": "application/pdf",
- "extension": ".pdf",
- "size": -1,
- }
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=_file_tool_transport(expected_source=expected_source)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client,
- dify_api_http_client=client,
- )
- )[0]
- result = await tool.function_schema.call(
- {"source": {"transfer_method": "remote_url", "url": "https://example.com/report.pdf"}},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_resolves_tool_file_mapping_before_invocation() -> None:
- async def scenario() -> None:
- expected_source = {
- "dify_model_identity": "__dify__file__",
- "type": "custom",
- "url": "https://signed.example/report.pdf",
- "filename": "report.pdf",
- "mime_type": "application/pdf",
- "extension": ".pdf",
- "size": 42,
- }
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(
- transport=_file_tool_transport(
- expected_source=expected_source,
- download_response={
- "filename": "report.pdf",
- "mime_type": "application/pdf",
- "size": 42,
- "download_url": "https://signed.example/report.pdf",
+ return httpx.Response(
+ 200,
+ json={
+ "data": {
+ "download_url": "https://example.com/file.pdf",
+ "filename": "file.pdf",
+ "mime_type": "application/pdf",
+ "size": 10,
+ }
},
)
- ) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client,
- dify_api_http_client=client,
- )
- )[0]
- result = await tool.function_schema.call(
- {"source": {"transfer_method": "tool_file", "reference": "dify-file-ref:file-1"}},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_converts_files_parameter_values() -> None:
- async def scenario() -> None:
- expected_source = [
- {
- "dify_model_identity": "__dify__file__",
- "type": "custom",
- "url": "https://example.com/a.txt",
- "filename": "a.txt",
- "mime_type": "text/plain",
- "extension": ".txt",
- "size": -1,
- },
- {
- "dify_model_identity": "__dify__file__",
- "type": "custom",
- "url": "https://example.com/b.txt",
- "filename": "b.txt",
- "mime_type": "text/plain",
- "extension": ".txt",
- "size": -1,
- },
- ]
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=_file_tool_transport(expected_source=expected_source)) as client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "tools": _file_tools_config(parameter_type=DifyPluginToolParameterType.FILES),
- }
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client,
- dify_api_http_client=client,
- )
- )[0]
- result = await tool.function_schema.call(
- {"source": ["https://example.com/a.txt", "https://example.com/b.txt"]},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == 'found {"count": 1}'
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_rejects_multiple_values_for_single_file() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(500))) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client,
- dify_api_http_client=client,
- )
- )[0]
- result = await tool.function_schema.call(
- {"source": ["https://example.com/a.txt", "https://example.com/b.txt"]},
- None, # pyright: ignore[reportArgumentType]
- )
- assert "only accepts one file" in result
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_rejects_path_without_shell() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(500))) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _file_tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client,
- dify_api_http_client=client,
- )
- )[0]
- result = await tool.function_schema.call(
- {"source": "outputs/report.pdf"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert "require an active shell layer" in result
-
- asyncio.run(scenario())
-
-
-def test_plugin_tool_file_context_uploads_sandbox_path_and_resolves_signed_url() -> None:
- class FakeShell:
- script: str | None = None
-
- async def run_remote_script_complete(self, script: str, **_kwargs: object) -> object:
- self.script = script
- return SimpleNamespace(
- exit_code=0,
- status="done",
- output_complete=True,
- output=(
- "noise\n"
- "<<<DIFY_PLUGIN_TOOL_FILE_UPLOAD_BEGIN>>>"
- '{"transfer_method":"tool_file","reference":"dify-file-ref:file-1"}'
- "<<<DIFY_PLUGIN_TOOL_FILE_UPLOAD_END>>>\n"
- ),
- )
-
- class FakeFileClient:
- async def request_download(self, **_kwargs: object) -> object:
- return SimpleNamespace(
- filename="report.pdf",
- mime_type="application/pdf",
- size=42,
- download_url="https://signed.example/report.pdf",
- )
-
- async def scenario() -> None:
- shell = FakeShell()
- context = _PluginToolFileContext(
- file_client=FakeFileClient(), # pyright: ignore[reportArgumentType]
- execution_context=_execution_context_config(),
- shell=shell, # pyright: ignore[reportArgumentType]
- )
- result = await context.to_plugin_file_parameter("outputs/report.pdf")
-
- assert result == {
- "dify_model_identity": "__dify__file__",
- "type": "custom",
- "url": "https://signed.example/report.pdf",
- "filename": "report.pdf",
- "mime_type": "application/pdf",
- "extension": ".pdf",
- "size": 42,
- }
- assert shell.script is not None
- assert "outputs/report.pdf" in shell.script
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_requires_hidden_runtime_parameters_in_prepared_config() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=_tool_transport()) as client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "tools": _missing_hidden_parameter_tools_config(),
- }
- ) as run:
- with pytest.raises(ValueError, match="requires non-LLM runtime_parameters for: auth_scope"):
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_returns_agent_friendly_error_text() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(
- transport=_tool_transport(
- invoke_error_payload={
- "error_type": "PluginDaemonBadRequestError",
- "message": "missing query",
- }
- )
- ) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
- )[0]
- result = await tool.function_schema.call(
- {"query": "dify", "region": "global"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == "tool parameters validation error: missing query, please check your tool parameters"
-
- asyncio.run(scenario())
-
-
-def test_dify_plugin_tools_layer_propagates_unexpected_transport_errors() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
+ sent.append(payload["data"]["tool_parameters"]["source"])
+ return httpx.Response(
+ 200, text='data: {"code":0,"message":"ok","data":{"type":"text","message":{"text":"read"}}}\n'
)
- def handler(request: httpx.Request) -> httpx.Response:
- if request.url.path.endswith("/dispatch/tool/invoke"):
- raise RuntimeError("unexpected transport failure")
-
- raise AssertionError(f"Unexpected request path: {request.url.path}")
-
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
- )[0]
-
- with pytest.raises(RuntimeError, match="unexpected transport failure"):
- await tool.function_schema.call(
- {"query": "dify", "region": "global"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- asyncio.run(scenario())
-
-
- ("invoke_error_payload", "expected_text"),
- [
- (
- {
- "error_type": "PluginInvokeError",
- "message": json.dumps(
- {
- "error_type": "PluginDaemonUnauthorizedError",
- "message": "invalid api key",
- }
- ),
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ deps = Deps(
+ layers={
+ "tools": {"config": config.model_dump(mode="json"), "state": {}},
+ "execution_context": {"config": identity().model_dump(mode="json"), "state": {}},
},
- "Please check your tool provider credentials",
- ),
- (
- {
- "error_type": "PluginInvokeError",
- "message": json.dumps(
- {
- "error_type": "ToolNotFoundError",
- "message": "missing plugin tool",
- }
- ),
- },
- "there is not a tool named web_search",
- ),
- ],
-)
-def test_dify_plugin_tools_layer_maps_nested_plugin_invoke_errors_to_agent_text(
- invoke_error_payload: dict[str, object],
- expected_text: str,
-) -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
+ services=Services(client, client),
+ run_id="test",
)
- async with httpx.AsyncClient(transport=_tool_transport(invoke_error_payload=invoke_error_payload)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
- )[0]
- result = await tool.function_schema.call(
- {"query": "dify", "region": "global"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert result == expected_text
+ result = await invoke_native_tool(deps, tools_layer.Toolset("tools"), "read", {"source": value})
+ assert result.output == "read"
+ assert sent[0]["url"] == "https://example.com/file.pdf"
- asyncio.run(scenario())
-
-def test_dify_plugin_tools_layer_merges_blob_chunks_before_observation_conversion() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("tools", _tools_provider(), deps={"execution_context": "execution_context"}),
- ]
+async def test_model_assembly_reads_config_reference_and_borrows_shared_client():
+ config = ModelConfig(
+ plugin_id="langgenius/openai", model_provider="openai", model="demo", execution_context="renamed"
+ )
+ async with httpx.AsyncClient() as client:
+ deps = Deps(
+ layers={
+ "llm": {"config": config.model_dump(mode="json"), "state": {}},
+ "renamed": {"config": identity().model_dump(mode="json"), "state": {}},
+ },
+ services=Services(client, client),
+ run_id="test",
)
- async with httpx.AsyncClient(transport=_tool_transport(chunked_blob=True)) as client:
- async with compositor.enter(
- configs={"execution_context": _execution_context_config(), "tools": _tools_config()}
- ) as run:
- tool = (
- await run.get_layer("tools", DifyPluginToolsLayer).get_tools(
- http_client=client, dify_api_http_client=client
- )
- )[0]
- result = await tool.function_schema.call(
- {"query": "dify", "region": "global"},
- None, # pyright: ignore[reportArgumentType]
- )
-
- assert "hello world" in result
- assert "sequence=0" not in result
-
- asyncio.run(scenario())
+ model = ModelCapability("llm").build_model(deps)
+ assert model.model_name == "demo"
+ assert model.provider.client.http_client is client
+ assert model.provider.name == "DifyAPI/langgenius/openai"
diff --git a/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py b/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py
index 2c26f0dfb14..34aa332c5d8 100644
--- a/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py
+++ b/dify-agent/tests/local/dify_agent/layers/execution_context/test_configs.py
@@ -1,32 +1,24 @@
import pytest
from pydantic import ValidationError
-
import dify_agent.layers.execution_context as execution_context_exports
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
def test_execution_context_package_exports_client_safe_config_symbols_only() -> None:
assert execution_context_exports.__all__ == [
- "DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID",
"DifyExecutionContextAgentConfigVersionKind",
"DifyExecutionContextAgentMode",
"DifyExecutionContextInvokeFrom",
"DifyExecutionContextLayerConfig",
"DifyExecutionContextUserFrom",
]
- assert execution_context_exports.DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID == "dify.execution_context"
assert not hasattr(execution_context_exports, "DifyExecutionContextLayer")
def test_execution_context_accepts_real_invoke_from_user_from_and_agent_mode() -> None:
config = DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="end-user",
- invoke_from="web-app",
- agent_mode="agent_app",
+ tenant_id="tenant-1", user_id="user-1", user_from="end-user", invoke_from="web-app", agent_mode="agent_app"
)
-
assert config.user_from == "end-user"
assert config.invoke_from == "web-app"
assert config.agent_mode == "agent_app"
@@ -53,14 +45,12 @@ def test_execution_context_layer_config_forbids_runtime_settings_and_unknown_fie
agent_mode="workflow_run",
invoke_from="service-api",
)
-
assert config.tenant_id == "tenant-1"
assert config.user_id == "user-1"
assert config.user_from == "account"
assert config.workflow_id == "workflow-1"
assert config.agent_mode == "workflow_run"
assert config.invoke_from == "service-api"
-
with pytest.raises(ValidationError):
_ = DifyExecutionContextLayerConfig.model_validate(
{
@@ -71,7 +61,6 @@ def test_execution_context_layer_config_forbids_runtime_settings_and_unknown_fie
"daemon_url": "http://daemon",
}
)
-
with pytest.raises(ValidationError):
_ = DifyExecutionContextLayerConfig.model_validate(
{
diff --git a/dify-agent/tests/local/dify_agent/layers/execution_context/test_layer.py b/dify-agent/tests/local/dify_agent/layers/execution_context/test_layer.py
deleted file mode 100644
index cc8ccb29c78..00000000000
--- a/dify-agent/tests/local/dify_agent/layers/execution_context/test_layer.py
+++ /dev/null
@@ -1,94 +0,0 @@
-import asyncio
-
-import httpx
-import pytest
-
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-
-
-def _execution_context_layer() -> DifyExecutionContextLayer:
- return DifyExecutionContextLayer.from_config_with_settings(
- DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- daemon_url="http://plugin-daemon",
- daemon_api_key="daemon-secret",
- )
-
-
-def test_execution_context_type_id_constant_matches_implementation_class() -> None:
- assert DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID == DifyExecutionContextLayer.type_id
-
-
-def test_execution_context_layer_creates_tool_client_from_shared_http_client() -> None:
- async def scenario() -> None:
- execution_context = _execution_context_layer()
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(200))) as client:
- tool_client = execution_context.create_tool_client(plugin_id="langgenius/tools", http_client=client)
-
- assert tool_client.http_client is client
- assert tool_client.tenant_id == "tenant-1"
- assert tool_client.user_id == "user-1"
- assert tool_client.plugin_id == "langgenius/tools"
- assert tool_client.plugin_daemon_url == "http://plugin-daemon"
- assert tool_client.plugin_daemon_api_key == "daemon-secret"
- assert client.is_closed is False
-
- asyncio.run(scenario())
-
-
-def test_execution_context_layer_rejects_closed_shared_http_client() -> None:
- async def scenario() -> None:
- execution_context = _execution_context_layer()
- client = httpx.AsyncClient(trust_env=False)
- await client.aclose()
-
- with pytest.raises(RuntimeError, match="open shared HTTP client"):
- _ = execution_context.create_tool_client(plugin_id="langgenius/tools", http_client=client)
-
- asyncio.run(scenario())
-
-
-def test_execution_context_layer_lifecycle_does_not_manage_http_client() -> None:
- from agenton.compositor import Compositor, LayerNode, LayerProvider
-
- provider = LayerProvider.from_factory(
- layer_type=DifyExecutionContextLayer,
- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(
- DifyExecutionContextLayerConfig.model_validate(config),
- daemon_url="http://plugin-daemon",
- daemon_api_key="daemon-secret",
- ),
- )
-
- async def scenario() -> None:
- compositor = Compositor([LayerNode("execution_context", provider)])
- async with httpx.AsyncClient(transport=httpx.MockTransport(lambda _request: httpx.Response(200))) as client:
- async with compositor.enter(
- configs={
- "execution_context": DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- )
- }
- ) as run:
- execution_context = run.get_layer("execution_context", DifyExecutionContextLayer)
- tool_client = execution_context.create_tool_client(
- plugin_id="langgenius/tools",
- http_client=client,
- )
- run.suspend_layer_on_exit("execution_context")
-
- assert run.session_snapshot is not None
- assert tool_client.http_client is client
- assert client.is_closed is False
-
- asyncio.run(scenario())
diff --git a/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py b/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py
index 17134bf3844..17eb267378f 100644
--- a/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/knowledge/test_layer.py
@@ -1,554 +1,185 @@
-import asyncio
+"""Knowledge module behavior using actual native Agent hooks and tool dispatch."""
+
import json
import httpx
import pytest
-from pydantic_ai import Tool
-
-from agenton.compositor import Compositor, LayerNode, LayerProvider
-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-from dify_agent.layers.knowledge.client import (
- DifyKnowledgeBaseClient,
- DifyKnowledgeBaseClientError,
- DifyKnowledgeRetrieveResponse,
-)
-from dify_agent.layers.knowledge.configs import DifyKnowledgeBaseLayerConfig
-from dify_agent.layers.knowledge.layer import (
- BLANK_QUERY_OBSERVATION,
- DifyKnowledgeBaseLayer,
- NO_RESULTS_OBSERVATION,
- TEMPORARY_UNAVAILABLE_OBSERVATION,
-)
-
-
-def _execution_context_config(**overrides: object) -> DifyExecutionContextLayerConfig:
- payload: dict[str, object] = {
- "tenant_id": "tenant-1",
- "user_id": "user-1",
- "user_from": "account",
- "app_id": "app-1",
- "agent_mode": "agent_app",
- "invoke_from": "web-app",
- }
- payload.update(overrides)
- return DifyExecutionContextLayerConfig.model_validate(payload)
-
-
-def _knowledge_config(**overrides: object) -> DifyKnowledgeBaseLayerConfig:
- set_payload: dict[str, object] = {
- "id": "support",
- "name": "Support KB",
- "datasets": [{"id": "dataset-1"}],
- "query": {"mode": "generated_query"},
- "retrieval": {"mode": "multiple", "top_k": 4},
- }
- for key in ("id", "name", "description", "datasets", "query", "retrieval", "metadata_filtering"):
- if key in overrides:
- set_payload[key] = overrides.pop(key)
- if "dataset_ids" in overrides:
- dataset_ids = overrides.pop("dataset_ids")
- assert isinstance(dataset_ids, list)
- set_payload["datasets"] = [{"id": dataset_id} for dataset_id in dataset_ids]
- payload: dict[str, object] = {
- "sets": [set_payload],
- }
- payload.update(overrides)
- return DifyKnowledgeBaseLayerConfig.model_validate(payload)
-
-
-def _execution_context_provider() -> LayerProvider[DifyExecutionContextLayer]:
- return LayerProvider.from_factory(
- layer_type=DifyExecutionContextLayer,
- create=lambda config: DifyExecutionContextLayer.from_config_with_settings(
- DifyExecutionContextLayerConfig.model_validate(config),
- daemon_url="http://plugin-daemon",
- daemon_api_key="daemon-secret",
- ),
- )
-
-
-def _knowledge_provider() -> LayerProvider[DifyKnowledgeBaseLayer]:
- return LayerProvider.from_factory(
- layer_type=DifyKnowledgeBaseLayer,
- create=lambda config: DifyKnowledgeBaseLayer.from_config_with_settings(
- DifyKnowledgeBaseLayerConfig.model_validate(config),
- inner_api_url="http://dify-api",
- inner_api_key="inner-secret",
- ),
- )
-
-
-def test_knowledge_layer_exposes_one_set_scoped_tool_definition() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient() as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- tool_def = await tool.prepare_tool_def(None) # pyright: ignore[reportArgumentType]
- assert isinstance(tool, Tool)
- assert tool.name == "knowledge_base_search"
- assert tool.description is not None
- assert "Pick one configured set_name" in tool.description
- assert tool_def is not None
- assert tool_def.description is not None
- assert "Pick one configured set_name" in tool_def.description
- assert tool_def.parameters_json_schema == {
- "type": "object",
- "properties": {
- "set_name": {
- "type": "string",
- "enum": ["Support KB"],
- "description": "Knowledge set to search.",
- },
- "query": {
- "type": "string",
- "description": "Search query for the selected knowledge set.",
- },
- },
- "required": ["set_name", "query"],
- "additionalProperties": False,
- }
-
- asyncio.run(scenario())
+from pydantic_ai import Agent
+from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, UserPromptPart
+from pydantic_ai.models.function import FunctionModel
-
-def test_knowledge_layer_rejects_blank_query_locally() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient() as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": " "},
- None, # pyright: ignore[reportArgumentType]
- )
- assert result == BLANK_QUERY_OBSERVATION
-
- asyncio.run(scenario())
-
-
-def test_knowledge_layer_exposes_no_tool_when_all_sets_are_user_query(monkeypatch: pytest.MonkeyPatch) -> None:
- async def fake_retrieve(self: DifyKnowledgeBaseClient, **_kwargs: object) -> DifyKnowledgeRetrieveResponse:
- del self
- return DifyKnowledgeRetrieveResponse.model_validate({"results": [], "usage": {}})
-
- monkeypatch.setattr(DifyKnowledgeBaseClient, "retrieve", fake_retrieve)
-
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient() as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(query={"mode": "user_query", "value": "release notes"}),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- assert await knowledge_layer.get_tools(http_client=http_client) == []
-
- asyncio.run(scenario())
+from dify_agent.layers.knowledge.layer import Capability, Config, State, TEMPORARY_UNAVAILABLE_OBSERVATION
+from dify_agent.layers.knowledge.client import DifyKnowledgeBaseClientError
+from dify_agent.layers.execution_context.configs import DifyExecutionContextLayerConfig
+from dify_agent.runtime.context import Deps, Services
+from tests.local.dify_agent.module_support import invoke_native_tool
-def test_knowledge_layer_fetches_user_query_sets_on_context_entry(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_requests: list[dict[str, object]] = []
-
- async def fake_retrieve(self: DifyKnowledgeBaseClient, **kwargs: object) -> DifyKnowledgeRetrieveResponse:
- del self
- seen_requests.append(kwargs)
- return DifyKnowledgeRetrieveResponse.model_validate(
+def config(*, eager=False, query="release", dataset="dataset"):
+ return Config(
+ sets=[
{
- "results": [
- {
- "metadata": {
- "_source": "knowledge",
- "dataset_name": "Docs",
- "document_name": "Release.md",
- "score": 0.8,
- },
- "title": "Release",
- "files": [],
- "content": "Version notes",
- "summary": None,
- }
- ],
- "usage": {},
+ "id": "support",
+ "name": "Support",
+ "datasets": [{"id": dataset}],
+ "query": {"mode": "user_query", "value": query} if eager else {"mode": "generated_query"},
+ "retrieval": {"mode": "multiple", "top_k": 4},
}
- )
-
- monkeypatch.setattr(DifyKnowledgeBaseClient, "retrieve", fake_retrieve)
-
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(query={"mode": "user_query", "value": "release notes"}),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- assert len(seen_requests) == 1
- assert seen_requests[0]["query"] == "release notes"
- assert seen_requests[0]["dataset_ids"] == ["dataset-1"]
- assert knowledge_layer.runtime_state.eager_config_fingerprint
- assert knowledge_layer.runtime_state.eager_results[0].status == "success"
- assert knowledge_layer.user_prompts == [
- "Knowledge retrieval results:\n\n"
- "Set: Support KB\n"
- "Query: release notes\n"
- "Results:\n"
- "1. Title: Release\n"
- " Dataset: Docs\n"
- " Document: Release.md\n"
- " Score: 0.8\n"
- " Content: Version notes"
- ]
- await knowledge_layer.on_context_resume()
- assert len(seen_requests) == 1
-
- asyncio.run(scenario())
+ ]
+ )
- ("field_name", "field_value"),
- [
- ("user_id", None),
- ("user_from", None),
- ("app_id", None),
- ],
-)
-def test_knowledge_layer_fails_fast_when_execution_context_is_missing_required_fields(
- field_name: str,
- field_value: object,
-) -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient() as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- execution_context_layer = run.get_layer("execution_context", DifyExecutionContextLayer)
- setattr(execution_context_layer.config, field_name, field_value)
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- with pytest.raises(ValueError, match=field_name):
- _ = await knowledge_layer.get_tools(http_client=http_client)
+def deps_for(client, config, state=None):
+ identity = DifyExecutionContextLayerConfig(
+ tenant_id="tenant",
+ user_id="user",
+ user_from="account",
+ app_id="app",
+ agent_mode="agent_app",
+ invoke_from="web-app",
+ )
+ return Deps(
+ layers={
+ "knowledge": {"config": config.model_dump(mode="json"), "state": state or State().model_dump(mode="json")},
+ "execution_context": {"config": identity.model_dump(mode="json"), "state": {}},
+ },
+ services=Services(client, client),
+ run_id="test",
+ )
- asyncio.run(scenario())
+async def test_eager_results_are_in_user_role_and_cache_uses_current_config():
+ requests = []
-def test_knowledge_layer_formats_results_and_truncates_observation() -> None:
- def handler(_request: httpx.Request) -> httpx.Response:
+ def handler(request):
+ assert request.url.path == "/inner/api/knowledge/retrieve"
+ requests.append(json.loads(request.content))
return httpx.Response(
200,
json={
"results": [
{
- "metadata": {
- "_source": "knowledge",
- "dataset_name": "Docs",
- "document_name": "Guide.md",
- "score": 0.9,
- },
- "title": "Guide",
+ "metadata": {"dataset_name": "Docs", "document_name": "Release", "score": 0.8},
+ "title": "Release",
"files": [],
- "content": "ABCDEFGHIJKL",
- "summary": None,
+ "content": "Version notes",
}
],
"usage": {},
},
)
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(max_result_content_chars=8, max_observation_chars=160),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert result.startswith("Knowledge base search results:\n1. Title: Guide")
- assert "Dataset: Docs" in result
- assert "Document: Guide.md" in result
- assert "Score: 0.9" in result
- assert "Content: ABCDE..." in result
- assert len(result) <= 160
-
- asyncio.run(scenario())
+ seen = []
+ async def model(messages, info):
+ assert info.function_tools == []
+ seen.append(list(messages))
+ return ModelResponse(parts=[TextPart("done")])
-def test_knowledge_layer_returns_no_results_observation() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(
- transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={"results": [], "usage": {}}))
- ) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert result == NO_RESULTS_OBSERVATION
-
- asyncio.run(scenario())
-
-
-def test_knowledge_layer_converts_retryable_failures_into_observation() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
- )
- async with httpx.AsyncClient(
- transport=httpx.MockTransport(
- lambda _request: httpx.Response(429, json={"code": "knowledge_rate_limited", "message": "slow down"})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ deps = deps_for(client, config(eager=True))
+ for _ in range(2):
+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(
+ "question", deps=deps
)
- ) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert result == TEMPORARY_UNAVAILABLE_OBSERVATION
-
- asyncio.run(scenario())
+ assert len(requests) == 1
+ assert requests[0]["caller"]["tenant_id"] == "tenant"
+ assert requests[0]["dataset_ids"] == ["dataset"]
+ prompts = [
+ p.content for m in seen[0] if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, UserPromptPart)
+ ]
+ assert prompts[0] == "question"
+ assert "Knowledge retrieval results" in prompts[1]
+ assert "Version notes" in prompts[1]
+ assert deps.layers["knowledge"]["state"]["eager_results"][0]["status"] == "success"
+ old_fingerprint = deps.layers["knowledge"]["state"]["eager_config_fingerprint"]
+ deps.layers["knowledge"]["config"] = config(eager=True, query="changed", dataset="new").model_dump(mode="json")
+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(
+ "question", deps=deps
+ )
+ assert len(requests) == 2
+ assert requests[1]["query"] == "changed" and requests[1]["dataset_ids"] == ["new"]
+ assert deps.layers["knowledge"]["state"]["eager_config_fingerprint"] != old_fingerprint
+ assert not client.is_closed
@pytest.mark.parametrize(
- "transport_error",
+ "query,status,expected",
[
- lambda request: httpx.ReadTimeout("timed out", request=request),
- lambda request: httpx.ConnectError("connection failed", request=request),
+ ("release", 200, "No relevant knowledge base results"),
+ (" ", 200, "requires a non-empty query"),
+ ("release", 429, "temporarily unavailable"),
],
)
-def test_knowledge_layer_converts_retryable_transport_failures_into_observation(transport_error) -> None:
- def handler(request: httpx.Request) -> httpx.Response:
- raise transport_error(request)
+async def test_generated_query_native_tool_preserves_local_validation_and_retry_policy(query, status, expected):
+ requests = []
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
+ def handler(request):
+ requests.append(json.loads(request.content))
+ return httpx.Response(
+ status, json={"results": [], "usage": {}} if status == 200 else {"code": "busy", "message": "busy"}
)
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert result == TEMPORARY_UNAVAILABLE_OBSERVATION
- asyncio.run(scenario())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ deps = deps_for(client, config())
+ def inspect(info):
+ schema = info.function_tools[0].parameters_json_schema
+ assert schema["properties"]["set_name"]["enum"] == ["Support"]
+ assert set(schema["properties"]) == {"set_name", "query"}
-def test_knowledge_layer_raises_non_retryable_client_errors() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
+ result = await invoke_native_tool(
+ deps,
+ Capability("knowledge").get_toolset(),
+ "knowledge_base_search",
+ {"set_name": "Support", "query": query},
+ inspect=inspect,
)
- async with httpx.AsyncClient(
- transport=httpx.MockTransport(
- lambda _request: httpx.Response(403, json={"code": "dataset_tenant_mismatch", "message": "forbidden"})
- )
- ) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- with pytest.raises(DifyKnowledgeBaseClientError) as exc_info:
- await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert exc_info.value.status_code == 403
+ assert expected in result.output
+ assert len(requests) == (0 if not query.strip() else 1)
- asyncio.run(scenario())
-
-def test_knowledge_layer_raises_for_malformed_success_responses() -> None:
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
+async def test_nonretryable_eager_failure_leaves_previous_cache_for_retry():
+ async with httpx.AsyncClient(
+ transport=httpx.MockTransport(
+ lambda request: httpx.Response(404, json={"code": "dataset_not_found", "message": "missing"})
)
- async with httpx.AsyncClient(
- transport=httpx.MockTransport(lambda _request: httpx.Response(200, json={"bad": []}))
- ) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- with pytest.raises(DifyKnowledgeBaseClientError) as exc_info:
- await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert exc_info.value.error_code == "invalid_response"
- assert exc_info.value.retryable is False
-
- asyncio.run(scenario())
+ ) as client:
+ deps = deps_for(client, config(eager=True), {"eager_config_fingerprint": "previous", "eager_results": []})
+ async def model(messages, info):
+ raise AssertionError("model must not execute after eager failure")
-def test_knowledge_layer_sends_execution_context_and_static_config_to_inner_api() -> None:
- def handler(request: httpx.Request) -> httpx.Response:
- payload = json.loads(request.content.decode("utf-8"))
- assert request.headers["X-Inner-Api-Key"] == "inner-secret"
- assert payload["caller"] == {
- "tenant_id": "tenant-1",
- "user_id": "user-1",
- "app_id": "app-1",
- "user_from": "account",
- "invoke_from": "web-app",
- }
- assert payload["dataset_ids"] == ["dataset-1", "dataset-2"]
- assert payload["query"] == "reset"
- assert payload["retrieval"]["top_k"] == 2
- assert payload["metadata_filtering"] == {
- "mode": "manual",
- "conditions": {
- "logical_operator": "and",
- "conditions": [
- {
- "name": "category",
- "comparison_operator": "contains",
- "value": "auth",
- }
- ],
- },
- }
- return httpx.Response(200, json={"results": [], "usage": {}})
+ with pytest.raises(DifyKnowledgeBaseClientError):
+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(
+ "question", deps=deps
+ )
+ assert deps.layers["knowledge"]["state"]["eager_config_fingerprint"] == "previous"
+
+
+async def test_retryable_eager_failure_is_saved_as_user_observation():
+ async with httpx.AsyncClient(
+ transport=httpx.MockTransport(lambda request: httpx.Response(429, json={"code": "busy", "message": "busy"}))
+ ) as client:
+ deps = deps_for(client, config(eager=True))
+
+ async def model(messages, info):
+ assert any(
+ TEMPORARY_UNAVAILABLE_OBSERVATION in str(p.content)
+ for m in messages
+ if isinstance(m, ModelRequest)
+ for p in m.parts
+ if isinstance(p, UserPromptPart)
+ )
+ return ModelResponse(parts=[TextPart("done")])
- async def scenario() -> None:
- compositor = Compositor(
- [
- LayerNode("execution_context", _execution_context_provider()),
- LayerNode("knowledge", _knowledge_provider(), deps={"execution_context": "execution_context"}),
- ]
+ await Agent(FunctionModel(model), deps_type=Deps, capabilities=[Capability("knowledge")]).run(
+ "question", deps=deps
)
- async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http_client:
- async with compositor.enter(
- configs={
- "execution_context": _execution_context_config(),
- "knowledge": _knowledge_config(
- dataset_ids=["dataset-1", "dataset-2"],
- retrieval={"mode": "multiple", "top_k": 2},
- metadata_filtering={
- "mode": "manual",
- "conditions": {
- "logical_operator": "and",
- "conditions": [
- {
- "name": "category",
- "comparison_operator": "contains",
- "value": "auth",
- }
- ],
- },
- },
- ),
- }
- ) as run:
- knowledge_layer = run.get_layer("knowledge", DifyKnowledgeBaseLayer)
- tool = (await knowledge_layer.get_tools(http_client=http_client))[0]
- result = await tool.function_schema.call( # pyright: ignore[reportArgumentType]
- {"set_name": "Support KB", "query": "reset"},
- None, # pyright: ignore[reportArgumentType]
- )
- assert result == NO_RESULTS_OBSERVATION
-
- asyncio.run(scenario())
+ state = State.model_validate(deps.layers["knowledge"]["state"])
+ assert state.eager_results[0].status == "temporarily_unavailable"
+ assert state.eager_config_fingerprint is not None
diff --git a/dify-agent/tests/local/dify_agent/layers/output/test_configs.py b/dify-agent/tests/local/dify_agent/layers/output/test_configs.py
index ad7cca5ab22..bcd44ad556f 100644
--- a/dify-agent/tests/local/dify_agent/layers/output/test_configs.py
+++ b/dify-agent/tests/local/dify_agent/layers/output/test_configs.py
@@ -1,10 +1,10 @@
import pytest
from pydantic import JsonValue, TypeAdapter, ValidationError
from pydantic_ai.output import ToolOutput
-
import dify_agent.layers.output as output_exports
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
-from dify_agent.layers.output.output_layer import DifyOutputLayer
+from dify_agent.layers.output import DifyOutputLayerConfig
+from dify_agent.layers.output.output_layer import Capability
+from tests.local.dify_agent.module_support import deps_for
def _json_schema() -> dict[str, JsonValue]:
@@ -25,43 +25,24 @@ def _recursive_json_schema() -> dict[str, JsonValue]:
"type": "object",
"properties": {"node": {"$ref": "#/$defs/node"}},
"$defs": {
- "node": {
- "type": "object",
- "properties": {"child": {"$ref": "#/$defs/node"}},
- "additionalProperties": False,
- }
+ "node": {"type": "object", "properties": {"child": {"$ref": "#/$defs/node"}}, "additionalProperties": False}
},
"additionalProperties": False,
}
def _remote_ref_schema() -> dict[str, JsonValue]:
- return {
- "type": "object",
- "properties": {
- "title": {"$ref": "https://example.com/schema.json"},
- },
- }
+ return {"type": "object", "properties": {"title": {"$ref": "https://example.com/schema.json"}}}
def _literal_dollar_ref_value_schema() -> dict[str, JsonValue]:
return {
"type": "object",
"properties": {
- "payload": {
- "const": {
- "$ref": "https://example.com/literal",
- "kind": "literal",
- },
- },
+ "payload": {"const": {"$ref": "https://example.com/literal", "kind": "literal"}},
"metadata": {
"type": "object",
- "examples": [
- {
- "$ref": "https://example.com/example",
- "note": "example value",
- }
- ],
+ "examples": [{"$ref": "https://example.com/example", "note": "example value"}],
},
},
"required": ["payload", "metadata"],
@@ -72,42 +53,23 @@ def _literal_dollar_ref_value_schema() -> dict[str, JsonValue]:
def _object_local_definitions_ref_schema() -> dict[str, JsonValue]:
return {
"type": "object",
- "properties": {
- "items": {"$ref": "#/definitions/itemArray"},
- },
+ "properties": {"items": {"$ref": "#/definitions/itemArray"}},
"required": ["items"],
- "definitions": {
- "itemArray": {
- "type": "array",
- "items": {"type": "string"},
- },
- },
+ "definitions": {"itemArray": {"type": "array", "items": {"type": "string"}}},
}
def _object_local_defs_ref_schema() -> dict[str, JsonValue]:
return {
"type": "object",
- "properties": {
- "items": {"$ref": "#/$defs/itemArray"},
- },
+ "properties": {"items": {"$ref": "#/$defs/itemArray"}},
"required": ["items"],
- "$defs": {
- "itemArray": {
- "type": "array",
- "items": {"type": "string"},
- },
- },
+ "$defs": {"itemArray": {"type": "array", "items": {"type": "string"}}},
}
def _invalid_json_schema() -> dict[str, JsonValue]:
- return {
- "type": "object",
- "properties": {
- "title": {"type": "wat"},
- },
- }
+ return {"type": "object", "properties": {"title": {"type": "wat"}}}
def _validated_output_type(output_spec: object) -> object:
@@ -116,23 +78,14 @@ def _validated_output_type(output_spec: object) -> object:
def test_output_package_exports_client_safe_config_symbols_only() -> None:
- assert output_exports.__all__ == ["DIFY_OUTPUT_LAYER_TYPE_ID", "DifyOutputLayerConfig"]
- assert output_exports.DIFY_OUTPUT_LAYER_TYPE_ID == "dify.output"
+ assert output_exports.__all__ == ["DifyOutputLayerConfig"]
assert not hasattr(output_exports, "DifyOutputLayer")
def test_output_layer_config_accepts_valid_object_schema_without_public_tool_name() -> None:
config = DifyOutputLayerConfig(json_schema=_json_schema())
-
- assert DIFY_OUTPUT_LAYER_TYPE_ID == "dify.output"
assert hasattr(config, "name") is False
- assert config.model_dump(mode="json") == {
- "json_schema": _json_schema(),
- "description": None,
- "strict": None,
- }
- assert config.description is None
- assert config.strict is None
+ assert config.model_dump(mode="json") == {"json_schema": _json_schema(), "description": None, "strict": None}
def test_output_layer_config_rejects_non_object_top_level_json_schema() -> None:
@@ -153,19 +106,13 @@ def test_output_layer_config_rejects_invalid_input(payload: dict[str, object], m
def test_output_layer_builds_validated_output_contract_for_object_schema() -> None:
- config = DifyOutputLayerConfig(
- json_schema=_json_schema(),
- description="Structured incident summary.",
- strict=True,
- )
-
- layer = DifyOutputLayer.from_config(config)
- output_contract = layer.build_output_contract()
+ config = DifyOutputLayerConfig(json_schema=_json_schema(), description="Structured incident summary.", strict=True)
+ layer = _output(config)
+ output_contract = layer
output_type = output_contract.output_type
output_schema = TypeAdapter(output_type.output).json_schema() if isinstance(output_type, ToolOutput) else {}
valid_output = {"title": "Database outage", "severity": "high", "actions": ["page on-call"]}
output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))
-
assert isinstance(output_type, ToolOutput)
assert output_type.name == "final_output"
assert output_type.description is None
@@ -191,39 +138,27 @@ def test_output_layer_builds_validated_output_contract_for_object_schema() -> No
),
],
)
-def test_output_layer_object_contract_retries_invalid_model_output(invalid_output: JsonValue, message: str) -> None:
- output_contract = DifyOutputLayer.from_config(
- DifyOutputLayerConfig(json_schema=_json_schema())
- ).build_output_contract()
+def test_output_layer_object_contract_rejects_invalid_output(invalid_output: JsonValue, message: str) -> None:
+ output_contract = _output(DifyOutputLayerConfig(json_schema=_json_schema()))
output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))
-
with pytest.raises(ValidationError, match=message):
_ = output_adapter.validate_python(invalid_output)
def test_output_layer_rejects_non_defs_local_ref_in_direct_object_schema() -> None:
- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_object_local_definitions_ref_schema()))
-
- with pytest.raises(ValueError, match=r"Only local refs under '#/\$defs/' are supported"):
- _ = layer.build_output_contract()
+ config = DifyOutputLayerConfig(json_schema=_object_local_definitions_ref_schema())
+ with pytest.raises(ValueError, match="Only local refs under '#/\\$defs/' are supported"):
+ _ = _output(config)
def test_output_layer_keeps_local_defs_ref_working_in_direct_object_schema() -> None:
- output_contract = DifyOutputLayer.from_config(
- DifyOutputLayerConfig(json_schema=_object_local_defs_ref_schema())
- ).build_output_contract()
+ output_contract = _output(DifyOutputLayerConfig(json_schema=_object_local_defs_ref_schema()))
output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))
output_schema = output_adapter.json_schema()
-
assert isinstance(output_contract.output_type, ToolOutput)
assert output_schema == {
"type": "object",
- "properties": {
- "items": {
- "type": "array",
- "items": {"type": "string"},
- },
- },
+ "properties": {"items": {"type": "array", "items": {"type": "string"}}},
"required": ["items"],
"title": "final_output",
}
@@ -231,44 +166,31 @@ def test_output_layer_keeps_local_defs_ref_working_in_direct_object_schema() ->
def test_output_layer_rejects_recursive_json_schema_during_contract_build() -> None:
- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_recursive_json_schema()))
-
+ config = DifyOutputLayerConfig(json_schema=_recursive_json_schema())
with pytest.raises(ValueError):
- _ = layer.build_output_contract()
+ _ = _output(config)
def test_output_layer_rejects_invalid_json_schema_during_contract_build() -> None:
- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_invalid_json_schema()))
-
+ config = DifyOutputLayerConfig(json_schema=_invalid_json_schema())
with pytest.raises(ValueError):
- _ = layer.build_output_contract()
+ _ = _output(config)
def test_output_layer_rejects_remote_ref_during_contract_build() -> None:
- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_remote_ref_schema()))
-
- with pytest.raises(ValueError, match=r"Remote \$ref values are not supported"):
- _ = layer.build_output_contract()
+ config = DifyOutputLayerConfig(json_schema=_remote_ref_schema())
+ with pytest.raises(ValueError, match="Remote \\$ref values are not supported"):
+ _ = _output(config)
def test_output_layer_allows_literal_dollar_ref_values_under_const_and_examples() -> None:
- layer = DifyOutputLayer.from_config(DifyOutputLayerConfig(json_schema=_literal_dollar_ref_value_schema()))
-
- output_contract = layer.build_output_contract()
+ layer = _output(DifyOutputLayerConfig(json_schema=_literal_dollar_ref_value_schema()))
+ output_contract = layer
output_adapter = TypeAdapter(_validated_output_type(output_contract.output_type))
-
assert output_adapter.validate_python(
- {
- "payload": {
- "$ref": "https://example.com/literal",
- "kind": "literal",
- },
- "metadata": {"note": "runtime value"},
- }
- ) == {
- "payload": {
- "$ref": "https://example.com/literal",
- "kind": "literal",
- },
- "metadata": {"note": "runtime value"},
- }
+ {"payload": {"$ref": "https://example.com/literal", "kind": "literal"}, "metadata": {"note": "runtime value"}}
+ ) == {"payload": {"$ref": "https://example.com/literal", "kind": "literal"}, "metadata": {"note": "runtime value"}}
+
+
+def _output(config):
+ return Capability("output").build_output_contract(deps_for("output", config))
diff --git a/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py b/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py
index a4dbdb1641b..fe953503e25 100644
--- a/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py
+++ b/dify-agent/tests/local/dify_agent/layers/shell/test_configs.py
@@ -1,9 +1,7 @@
import pytest
from pydantic import ValidationError
-
import dify_agent.layers.shell as shell_exports
from dify_agent.layers.shell import (
- DIFY_SHELL_LAYER_TYPE_ID,
DifyShellCliToolConfig,
DifyShellEnvVarConfig,
DifyShellLayerConfig,
@@ -13,26 +11,24 @@ from dify_agent.layers.shell import (
def test_shell_package_exports_client_safe_config_symbols_only() -> None:
assert shell_exports.__all__ == [
- "DIFY_SHELL_LAYER_TYPE_ID",
"DifyShellCliToolConfig",
"DifyShellEnvVarConfig",
"DifyShellLayerConfig",
"DifyShellSecretRefConfig",
]
- assert DIFY_SHELL_LAYER_TYPE_ID == "dify.shell"
assert not hasattr(shell_exports, "DifyShellLayer")
def test_shell_layer_config_defaults_and_forbids_unknown_fields() -> None:
config = DifyShellLayerConfig()
-
assert config.model_dump() == {
+ "runtime": "runtime",
+ "execution_context": "execution_context",
"cli_tools": [],
"env": [],
"secret_refs": [],
"redact_patterns": [],
}
-
with pytest.raises(ValidationError):
_ = DifyShellLayerConfig.model_validate({"entrypoint": "http://shellctl"})
@@ -50,7 +46,6 @@ def test_shell_layer_config_accepts_agent_soul_shell_settings() -> None:
env=[DifyShellEnvVarConfig(name="PROJECT_NAME", value="demo")],
secret_refs=[DifyShellSecretRefConfig(name="OPENAI_API_KEY", ref="credential-1")],
)
-
assert config.cli_tools[0].install_commands == ["apt-get update", "apt-get install -y ripgrep"]
assert config.cli_tools[0].env[0].name == "RG_CONFIG_PATH"
assert config.cli_tools[0].secret_refs[0].ref == "credential-2"
@@ -61,6 +56,5 @@ def test_shell_layer_config_accepts_agent_soul_shell_settings() -> None:
def test_shell_layer_config_rejects_invalid_env_names() -> None:
with pytest.raises(ValidationError):
_ = DifyShellEnvVarConfig(name="1_BAD", value="x")
-
with pytest.raises(ValidationError):
_ = DifyShellSecretRefConfig(name="BAD-NAME", ref="secret")
diff --git a/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py b/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py
index ae75ff1aea0..081da9d147a 100644
--- a/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/shell/test_layer.py
@@ -11,17 +11,14 @@ import pytest
import dify_agent.layers.shell.layer as shell_layer_module
import dify_agent.runtime.command_runner as command_runner_module
from dify_agent.layers.shell import (
- DIFY_SHELL_LAYER_TYPE_ID,
- DifyShellCliToolConfig,
DifyShellEnvVarConfig,
DifyShellLayerConfig,
)
from dify_agent.layers.shell.layer import (
CompleteRemoteCommandResult,
DEFAULT_TERMINATE_GRACE_SECONDS,
- DifyShellLayer,
- DifyShellLayerDeps,
- DifyShellRuntimeState,
+ ShellSession,
+ State,
)
from dify_agent.adapters.shell.protocols import (
ShellCommandResult,
@@ -30,11 +27,7 @@ from dify_agent.adapters.shell.protocols import (
ShellProviderError,
)
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-from dify_agent.layers.runtime import DifyRuntimeLayerConfig
-from dify_agent.layers.runtime.layer import DifyRuntimeLayer
from dify_agent.runtime_backend import (
- ExecutionBindingBackend,
RuntimeLayout,
RuntimeLease,
)
@@ -232,8 +225,8 @@ class FakeResource:
@dataclass(slots=True)
-class FakeProvider:
- """Test fixture retaining the old name while representing an active lease."""
+class FakeLeaseFixture:
+ """Command fixture for an acquired runtime lease."""
resource: FakeResource
@@ -243,34 +236,29 @@ def _layer(
commands: FakeCommands,
config: DifyShellLayerConfig | None = None,
shell_home_root: str = "/home",
-) -> tuple[DifyShellLayer, FakeProvider]:
- provider = FakeProvider(resource=FakeResource(commands=commands))
+) -> tuple[ShellSession, FakeLeaseFixture]:
+ provider = FakeLeaseFixture(resource=FakeResource(commands=commands))
root = shell_home_root.rstrip("/")
provider.resource.layout = RuntimeLayout(
home_dir=f"{root}/agent-1",
workspace_dir=f"{root}/agent-1/workspace/abc12ff",
)
- layer = DifyShellLayer.from_config_with_settings(
- config or DifyShellLayerConfig(),
- )
- runtime = DifyRuntimeLayer.from_config_with_backend(
- DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),
- backend=cast(ExecutionBindingBackend, object()),
- )
- runtime._lease = cast(RuntimeLease, cast(object, provider.resource))
- layer.deps = DifyShellLayerDeps(
- runtime=runtime,
- execution_context=None,
- )
+ from tests.local.dify_agent.module_support import deps_for
+
+ cfg = config or DifyShellLayerConfig()
+ cfg = cfg.model_copy(update={"execution_context": None})
+ deps = deps_for("shell", cfg, State().model_dump(mode="json"))
+ deps.resources.leases["runtime"] = cast(RuntimeLease, provider.resource)
+ layer = ShellSession("shell", deps)
return layer, provider
-def _bind_execution_context(layer: DifyShellLayer, *, agent_id: str | None = "agent-1") -> None:
- layer.deps.execution_context = DifyExecutionContextLayer.from_config_with_settings(
- _execution_context_config(agent_id=agent_id),
- daemon_url="http://plugin-daemon",
- daemon_api_key="",
- )
+def _bind_execution_context(layer: ShellSession, *, agent_id: str | None = "agent-1") -> None:
+ layer.deps.layers["execution_context"] = {
+ "config": _execution_context_config(agent_id=agent_id).model_dump(mode="json"),
+ "state": {},
+ }
+ layer.deps.layers["shell"]["config"]["execution_context"] = "execution_context"
def _execution_context_config(*, agent_id: str | None = None) -> DifyExecutionContextLayerConfig:
@@ -291,27 +279,14 @@ def _runtime_state(
sandbox_id: str | None = None,
job_ids: list[str] | None = None,
job_offsets: dict[str, int] | None = None,
-) -> DifyShellRuntimeState:
+) -> State:
del session_id, workspace_cwd, sandbox_id
- return DifyShellRuntimeState(
+ return State(
job_ids=[] if job_ids is None else job_ids,
job_offsets={} if job_offsets is None else job_offsets,
)
-def test_shell_type_id_constant_matches_implementation_class() -> None:
- assert DIFY_SHELL_LAYER_TYPE_ID == DifyShellLayer.type_id
-
-
-def test_shell_layer_tools_have_non_empty_descriptions() -> None:
- layer = DifyShellLayer.from_config_with_settings(DifyShellLayerConfig())
-
- descriptions = {tool.name: tool.description for tool in layer.tools}
-
- assert set(descriptions) == {"shell_run", "shell_wait", "shell_input", "shell_interrupt"}
- assert all(description and description.strip() for description in descriptions.values())
-
-
def test_shell_prefix_prompt_describes_workspace_as_temp_space() -> None:
prompt = shell_layer_module._SHELL_LAYER_PREFIX_PROMPT
@@ -321,33 +296,6 @@ def test_shell_prefix_prompt_describes_workspace_as_temp_space() -> None:
assert "<cwd>/.tmp" not in prompt
-def test_shell_layer_create_bootstraps_inside_sandbox_workspace() -> None:
- expected_home = "/home/agent-1"
- expected_workspace_cwd = "/home/agent-1/workspace/abc12ff"
-
- def run_handler(script: str, cwd: str | None, env: Mapping[str, str] | None, timeout: float) -> ShellCommandResult:
- assert env == {"HOME": expected_home}
- assert cwd == expected_workspace_cwd
- assert "apt-get install -y ripgrep" in script
- return _command_result("bootstrap-job", status="exited", done=True, exit_code=0)
-
- layer, provider = _layer(
- commands=FakeCommands(run_handler=run_handler),
- config=DifyShellLayerConfig(
- cli_tools=[DifyShellCliToolConfig(name="ripgrep", install_commands=["apt-get install -y ripgrep"])],
- ),
- )
- _bind_execution_context(layer)
-
- async def scenario() -> None:
- async with layer.resource_context():
- await layer.on_context_create()
-
- asyncio.run(scenario())
-
- assert [call.job_id for call in provider.resource.commands.delete_calls] == ["bootstrap-job"]
-
-
def test_shell_layer_uses_sandbox_layout_for_home_and_workspace_cwd() -> None:
expected_home = "/home/agent-1"
expected_workspace_cwd = "/home/agent-1/workspace/abc12ff"
@@ -363,14 +311,12 @@ def test_shell_layer_uses_sandbox_layout_for_home_and_workspace_cwd() -> None:
commands = FakeCommands(run_handler=run_handler)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
async def scenario() -> None:
- async with layer.resource_context():
- run_result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
- metadata, output = _parse_tagged_observation(run_result)
- assert metadata["job_id"] == "user-job"
- assert output == expected_home
+ run_result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
+ metadata, output = _parse_tagged_observation(run_result)
+ assert metadata["job_id"] == "user-job"
+ assert output == expected_home
asyncio.run(scenario())
@@ -378,55 +324,6 @@ def test_shell_layer_uses_sandbox_layout_for_home_and_workspace_cwd() -> None:
assert commands.delete_calls == []
-def test_shell_layer_suspend_cleans_tracked_jobs_without_owning_sandbox() -> None:
- commands = FakeCommands()
- layer, _provider = _layer(commands=commands)
- layer.runtime_state = _runtime_state()
- layer._job_agent_stub_tokens.update({"job-1": "token-1", "job-2": "token-2"})
-
- async def scenario() -> None:
- async with layer.resource_context():
- await layer.on_context_suspend()
-
- asyncio.run(scenario())
- assert commands.delete_calls == []
- assert layer._job_agent_stub_tokens == {}
-
-
-def test_shell_layer_resume_requires_active_sandbox_lease_only() -> None:
- commands = FakeCommands()
- layer, _provider = _layer(commands=commands)
- _bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
-
- async def scenario() -> None:
- async with layer.resource_context():
- await layer.on_context_resume()
-
- asyncio.run(scenario())
-
- assert commands.run_calls == []
-
-
-def test_shell_layer_delete_cleans_tracked_jobs_without_deleting_workspace() -> None:
- commands = FakeCommands()
- layer, _provider = _layer(commands=commands)
- _bind_execution_context(layer)
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 9})
- layer._job_agent_stub_tokens["user-job"] = "long-lived-test-token"
-
- async def scenario() -> None:
- async with layer.resource_context():
- await layer.on_context_delete()
-
- asyncio.run(scenario())
-
- assert [call.job_id for call in commands.delete_calls] == ["user-job"]
- assert layer.runtime_state.job_ids == []
- assert layer.runtime_state.job_offsets == {}
- assert layer._job_agent_stub_tokens == {}
-
-
def test_shell_layer_tools_map_inputs_and_maintain_offsets_with_tail_end() -> None:
def run_handler(script: str, cwd: str | None, env: Mapping[str, str] | None, timeout: float) -> ShellCommandResult:
assert script == "pwd"
@@ -478,51 +375,40 @@ def test_shell_layer_tools_map_inputs_and_maintain_offsets_with_tail_end() -> No
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- run_result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
- wait_result = await tools["shell_wait"].function_schema.call(
- {"job_id": "user-job", "timeout": 4.0},
- None, # pyright: ignore[reportArgumentType]
- )
- input_result = await tools["shell_input"].function_schema.call(
- {"job_id": "user-job", "text": "ls\n", "timeout": 5.0},
- None, # pyright: ignore[reportArgumentType]
- )
- interrupt_result = await tools["shell_interrupt"].function_schema.call(
- {"job_id": "user-job", "grace_seconds": 1.5},
- None, # pyright: ignore[reportArgumentType]
- )
-
- run_metadata, run_output = _parse_tagged_observation(run_result)
- wait_metadata, wait_output = _parse_tagged_observation(wait_result)
- input_metadata, input_output = _parse_tagged_observation(input_result)
- interrupt_metadata, interrupt_output = _parse_tagged_observation(interrupt_result)
-
- assert run_metadata == {
- "job_id": "user-job",
- "status": "running",
- "done": False,
- "exit_code": None,
- "output_path": "/tmp/resolved.log",
- }
- assert "head-output" in run_output
- assert "tail-output" in run_output
- assert wait_metadata["job_id"] == "user-job"
- assert wait_output == "more\n"
- assert input_metadata["exit_code"] == 0
- assert input_output == "file.txt\n"
- assert interrupt_metadata == {
- "job_id": "user-job",
- "status": "terminated",
- "done": True,
- "exit_code": 130,
- "output_path": "/tmp/resolved.log",
- }
- assert interrupt_output == "Job was interrupted."
+ run_result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
+ wait_result = await layer._tool_wait(**{"job_id": "user-job", "timeout": 4.0})
+ input_result = await layer._tool_input(**{"job_id": "user-job", "text": "ls\n", "timeout": 5.0})
+ interrupt_result = await layer._tool_interrupt(**{"job_id": "user-job", "grace_seconds": 1.5})
+
+ run_metadata, run_output = _parse_tagged_observation(run_result)
+ wait_metadata, wait_output = _parse_tagged_observation(wait_result)
+ input_metadata, input_output = _parse_tagged_observation(input_result)
+ interrupt_metadata, interrupt_output = _parse_tagged_observation(interrupt_result)
+
+ assert run_metadata == {
+ "job_id": "user-job",
+ "status": "running",
+ "done": False,
+ "exit_code": None,
+ "output_path": "/tmp/resolved.log",
+ }
+ assert "head-output" in run_output
+ assert "tail-output" in run_output
+ assert wait_metadata["job_id"] == "user-job"
+ assert wait_output == "more\n"
+ assert input_metadata["exit_code"] == 0
+ assert input_output == "file.txt\n"
+ assert interrupt_metadata == {
+ "job_id": "user-job",
+ "status": "terminated",
+ "done": True,
+ "exit_code": 130,
+ "output_path": "/tmp/resolved.log",
+ }
+ assert interrupt_output == "Job was interrupted."
asyncio.run(scenario())
@@ -552,22 +438,19 @@ def test_shell_run_keeps_original_offset_when_tail_lookup_fails_for_truncated_ou
commands = FakeCommands(run_handler=run_handler, tail_handler=tail_handler)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- run_result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
- metadata, output = _parse_tagged_observation(run_result)
- assert metadata == {
- "job_id": "user-job",
- "status": "running",
- "done": False,
- "exit_code": None,
- "output_path": "/tmp/current.log",
- }
- assert "head-output" in output
- assert set(metadata) == {"job_id", "status", "done", "exit_code", "output_path"}
+ run_result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
+ metadata, output = _parse_tagged_observation(run_result)
+ assert metadata == {
+ "job_id": "user-job",
+ "status": "running",
+ "done": False,
+ "exit_code": None,
+ "output_path": "/tmp/current.log",
+ }
+ assert "head-output" in output
asyncio.run(scenario())
@@ -590,18 +473,16 @@ def test_shell_run_formats_large_non_truncated_output_without_tail_lookup() -> N
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "cat large.log"}, None) # pyright: ignore[reportArgumentType]
- metadata, output = _parse_tagged_observation(result)
- assert metadata["output_path"] == "/tmp/large.log"
- assert output.startswith("head-y")
- assert "max output size is limited to 8192 bytes" in output
- assert output.endswith("(check the /tmp/large.log for full output)")
- assert "-tail" in output
+ result = await layer._tool_run(**{"script": "cat large.log"}) # pyright: ignore[reportArgumentType]
+ metadata, output = _parse_tagged_observation(result)
+ assert metadata["output_path"] == "/tmp/large.log"
+ assert output.startswith("head-y")
+ assert "max output size is limited to 8192 bytes" in output
+ assert output.endswith("(check the /tmp/large.log for full output)")
+ assert "-tail" in output
asyncio.run(scenario())
assert commands.tail_calls == []
@@ -613,21 +494,19 @@ def test_shell_interrupt_succeeds_when_tail_lookup_fails() -> None:
tail_handler=lambda job_id: (_ for _ in ()).throw(RuntimeError("tail unavailable")),
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))
layer._job_agent_stub_tokens["user-job"] = "actual-long-jwe-token"
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_interrupt"].function_schema.call({"job_id": "user-job"}, None) # pyright: ignore[reportArgumentType]
- metadata, output = _parse_tagged_observation(result)
- assert metadata == {
- "job_id": "user-job",
- "status": "terminated",
- "done": True,
- "exit_code": 130,
- }
- assert output == "Job was interrupted."
+ result = await layer._tool_interrupt(**{"job_id": "user-job"}) # pyright: ignore[reportArgumentType]
+ metadata, output = _parse_tagged_observation(result)
+ assert metadata == {
+ "job_id": "user-job",
+ "status": "terminated",
+ "done": True,
+ "exit_code": 130,
+ }
+ assert output == "Job was interrupted."
asyncio.run(scenario())
assert layer._job_agent_stub_tokens == {}
@@ -644,13 +523,11 @@ def test_shell_run_returns_provider_timeout_error_observation_without_unexpected
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
- _assert_error_observation(result, includes="timeout")
+ result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
+ _assert_error_observation(result, includes="timeout")
asyncio.run(scenario())
assert logged == []
@@ -666,16 +543,11 @@ def test_shell_wait_returns_provider_request_error_observation_with_job_id_and_n
)
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_wait"].function_schema.call(
- {"job_id": "user-job", "timeout": 4.0},
- None, # pyright: ignore[reportArgumentType]
- )
- _assert_error_observation(result, job_id="user-job", includes="request_error")
+ result = await layer._tool_wait(**{"job_id": "user-job", "timeout": 4.0})
+ _assert_error_observation(result, job_id="user-job", includes="request_error")
asyncio.run(scenario())
assert logged == []
@@ -691,16 +563,11 @@ def test_shell_input_returns_provider_timeout_error_observation_with_job_id_and_
)
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_input"].function_schema.call(
- {"job_id": "user-job", "text": "ls\n", "timeout": 5.0},
- None, # pyright: ignore[reportArgumentType]
- )
- _assert_error_observation(result, job_id="user-job", includes="timeout")
+ result = await layer._tool_input(**{"job_id": "user-job", "text": "ls\n", "timeout": 5.0})
+ _assert_error_observation(result, job_id="user-job", includes="timeout")
asyncio.run(scenario())
assert logged == []
@@ -716,16 +583,11 @@ def test_shell_interrupt_returns_provider_request_error_observation_with_job_id_
)
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_interrupt"].function_schema.call(
- {"job_id": "user-job", "grace_seconds": 1.5},
- None, # pyright: ignore[reportArgumentType]
- )
- _assert_error_observation(result, job_id="user-job", includes="request_error")
+ result = await layer._tool_interrupt(**{"job_id": "user-job", "grace_seconds": 1.5})
+ _assert_error_observation(result, job_id="user-job", includes="request_error")
asyncio.run(scenario())
assert logged == []
@@ -740,13 +602,11 @@ def test_shell_run_returns_error_observation_and_logs_unexpected_exception(
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
- _assert_error_observation(result, includes="boom")
+ result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
+ _assert_error_observation(result, includes="boom")
asyncio.run(scenario())
assert logged == [
@@ -765,16 +625,11 @@ def test_shell_wait_returns_error_observation_and_logs_unexpected_exception(
wait_handler=lambda job_id, offset, timeout: (_ for _ in ()).throw(_UnexpectedToolError("wait exploded"))
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 3}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_wait"].function_schema.call(
- {"job_id": "user-job", "timeout": 4.0},
- None, # pyright: ignore[reportArgumentType]
- )
- _assert_error_observation(result, job_id="user-job", includes="wait exploded")
+ result = await layer._tool_wait(**{"job_id": "user-job", "timeout": 4.0})
+ _assert_error_observation(result, job_id="user-job", includes="wait exploded")
asyncio.run(scenario())
assert logged == [
@@ -795,16 +650,11 @@ def test_shell_input_returns_error_observation_and_logs_unexpected_exception(
)
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 6}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_input"].function_schema.call(
- {"job_id": "user-job", "text": "ls\n", "timeout": 5.0},
- None, # pyright: ignore[reportArgumentType]
- )
- _assert_error_observation(result, job_id="user-job", includes="stdin exploded")
+ result = await layer._tool_input(**{"job_id": "user-job", "text": "ls\n", "timeout": 5.0})
+ _assert_error_observation(result, job_id="user-job", includes="stdin exploded")
asyncio.run(scenario())
assert logged == [
@@ -825,16 +675,11 @@ def test_shell_interrupt_returns_error_observation_and_logs_unexpected_exception
)
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_interrupt"].function_schema.call(
- {"job_id": "user-job", "grace_seconds": 1.5},
- None, # pyright: ignore[reportArgumentType]
- )
- _assert_error_observation(result, job_id="user-job", includes="interrupt exploded")
+ result = await layer._tool_interrupt(**{"job_id": "user-job", "grace_seconds": 1.5})
+ _assert_error_observation(result, job_id="user-job", includes="interrupt exploded")
asyncio.run(scenario())
assert logged == [
@@ -854,20 +699,18 @@ def test_shell_interrupt_logs_unexpected_tail_failure_but_still_succeeds(
tail_handler=lambda job_id: (_ for _ in ()).throw(_UnexpectedToolError("tail exploded")),
)
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22})
+ layer.save_state(_runtime_state(job_ids=["user-job"], job_offsets={"user-job": 22}))
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_interrupt"].function_schema.call({"job_id": "user-job"}, None) # pyright: ignore[reportArgumentType]
- metadata, output = _parse_tagged_observation(result)
- assert metadata == {
- "job_id": "user-job",
- "status": "terminated",
- "done": True,
- "exit_code": 130,
- }
- assert output == "Job was interrupted."
+ result = await layer._tool_interrupt(**{"job_id": "user-job"}) # pyright: ignore[reportArgumentType]
+ metadata, output = _parse_tagged_observation(result)
+ assert metadata == {
+ "job_id": "user-job",
+ "status": "terminated",
+ "done": True,
+ "exit_code": 130,
+ }
+ assert output == "Job was interrupted."
asyncio.run(scenario())
assert logged == [
@@ -902,12 +745,11 @@ def test_agent_stub_token_omits_workspace_session_identity() -> None:
layer, _provider = _layer(commands=FakeCommands(run_handler=run_handler))
_bind_execution_context(layer)
- layer.agent_stub_api_base_url = "http://localhost:5050/agent-stub"
- layer.agent_stub_token_factory = token_factory
+ layer.deps.services.agent_stub_api_base_url = "http://localhost:5050/agent-stub"
+ layer.deps.services.agent_stub_token_factory = token_factory
async def scenario() -> None:
- async with layer.resource_context():
- _ = await layer.run_remote_script_complete("true", inject_agent_stub_env=True)
+ _ = await layer.run_remote_script_complete("true", inject_agent_stub_env=True)
asyncio.run(scenario())
@@ -920,13 +762,11 @@ def test_shell_run_propagates_cancelled_error() -> None:
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- with pytest.raises(asyncio.CancelledError):
- await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
+ with pytest.raises(asyncio.CancelledError):
+ await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
asyncio.run(scenario())
@@ -953,15 +793,14 @@ def test_run_remote_script_complete_uses_read_output_before_wait_and_deletes_job
commands = FakeCommands(run_handler=run_handler, wait_handler=wait_handler)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await layer.run_remote_script_complete("printf 'abcdefghi'")
- assert isinstance(result, CompleteRemoteCommandResult)
- assert result.output == "abcdefghi"
- assert result.output_complete is True
- assert result.incomplete_reason is None
+ result = await layer.run_remote_script_complete("printf 'abcdefghi'")
+ assert isinstance(result, CompleteRemoteCommandResult)
+ assert result.output == "abcdefghi"
+ assert result.output_complete is True
+ assert result.incomplete_reason is None
asyncio.run(scenario())
assert events == ["run", "read_output", "wait"]
@@ -990,13 +829,12 @@ def test_run_remote_script_complete_uses_agent_specific_home_and_workspace_cwd()
commands = FakeCommands(run_handler=run_handler)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await layer.run_remote_script_complete("pwd")
- assert isinstance(result, CompleteRemoteCommandResult)
- assert result.output == expected_home
+ result = await layer.run_remote_script_complete("pwd")
+ assert isinstance(result, CompleteRemoteCommandResult)
+ assert result.output == expected_home
asyncio.run(scenario())
assert [call.job_id for call in commands.delete_calls] == ["remote-job"]
@@ -1023,13 +861,12 @@ def test_run_remote_script_complete_passes_config_env_values_to_shellctl_env() -
config=DifyShellLayerConfig(env=[DifyShellEnvVarConfig(name="API_TOKEN", value="inline-secret-value")]),
)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await layer.run_remote_script_complete("printenv API_TOKEN")
- assert isinstance(result, CompleteRemoteCommandResult)
- assert result.output == "inline-secret-value\n"
+ result = await layer.run_remote_script_complete("printenv API_TOKEN")
+ assert isinstance(result, CompleteRemoteCommandResult)
+ assert result.output == "inline-secret-value\n"
asyncio.run(scenario())
assert [call.job_id for call in commands.delete_calls] == ["remote-job"]
@@ -1056,13 +893,12 @@ def test_run_remote_script_uses_agent_specific_home_and_workspace_cwd() -> None:
commands = FakeCommands(run_handler=run_handler)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await layer.run_remote_script("pwd")
- assert isinstance(result, CompleteRemoteCommandResult)
- assert result.output == expected_home
+ result = await layer.run_remote_script("pwd")
+ assert isinstance(result, CompleteRemoteCommandResult)
+ assert result.output == expected_home
asyncio.run(scenario())
assert [call.job_id for call in commands.delete_calls] == ["remote-job"]
@@ -1088,15 +924,14 @@ def test_run_remote_script_complete_returns_incomplete_reason_for_output_limit()
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await layer.run_remote_script_complete("printf 'hello world'", max_output_bytes=5)
- assert result.output == "hello"
- assert result.output_complete is False
- assert result.incomplete_reason == "output_limit"
- assert result.status == "terminated"
+ result = await layer.run_remote_script_complete("printf 'hello world'", max_output_bytes=5)
+ assert result.output == "hello"
+ assert result.output_complete is False
+ assert result.incomplete_reason == "output_limit"
+ assert result.status == "terminated"
asyncio.run(scenario())
assert commands.wait_calls == []
@@ -1136,16 +971,15 @@ def test_run_remote_script_complete_returns_incomplete_reason_for_timeout(
)
layer, _provider = _layer(commands=commands)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await layer.run_remote_script_complete("sleep 10", timeout=60.0)
- assert result.output == "hello"
- assert result.output_complete is False
- assert result.incomplete_reason == "timeout"
- assert result.status == "terminated"
- assert result.exit_code == 130
+ result = await layer.run_remote_script_complete("sleep 10", timeout=60.0)
+ assert result.output == "hello"
+ assert result.output_complete is False
+ assert result.incomplete_reason == "timeout"
+ assert result.status == "terminated"
+ assert result.exit_code == 130
asyncio.run(scenario())
assert commands.wait_calls == []
@@ -1158,20 +992,15 @@ def test_run_remote_script_complete_returns_incomplete_reason_for_timeout(
def test_shell_layer_rejects_untracked_job_ids_without_provider_calls() -> None:
commands = FakeCommands()
layer, _provider = _layer(commands=commands)
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- wait_result = await tools["shell_wait"].function_schema.call({"job_id": "missing"}, None) # pyright: ignore[reportArgumentType]
- input_result = await tools["shell_input"].function_schema.call(
- {"job_id": "missing", "text": "hello"},
- None, # pyright: ignore[reportArgumentType]
- )
- interrupt_result = await tools["shell_interrupt"].function_schema.call({"job_id": "missing"}, None) # pyright: ignore[reportArgumentType]
- _assert_error_observation(wait_result, job_id="missing")
- _assert_error_observation(input_result, job_id="missing")
- _assert_error_observation(interrupt_result, job_id="missing")
+ wait_result = await layer._tool_wait(**{"job_id": "missing"}) # pyright: ignore[reportArgumentType]
+ input_result = await layer._tool_input(**{"job_id": "missing", "text": "hello"})
+ interrupt_result = await layer._tool_interrupt(**{"job_id": "missing"}) # pyright: ignore[reportArgumentType]
+ _assert_error_observation(wait_result, job_id="missing")
+ _assert_error_observation(input_result, job_id="missing")
+ _assert_error_observation(interrupt_result, job_id="missing")
asyncio.run(scenario())
assert commands.wait_calls == []
@@ -1181,19 +1010,18 @@ def test_shell_layer_rejects_untracked_job_ids_without_provider_calls() -> None:
def test_shell_layer_hooks_and_tools_fail_clearly_outside_active_resource_context() -> None:
layer, _provider = _layer(commands=FakeCommands())
- layer.deps.runtime._lease = None
- tools = {tool.name: tool for tool in layer.tools}
- layer.runtime_state = _runtime_state()
+ layer.deps.resources.leases.clear()
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- result = await tools["shell_run"].function_schema.call({"script": "pwd"}, None) # pyright: ignore[reportArgumentType]
- _assert_error_observation(result, includes="resource_context")
+ result = await layer._tool_run(**{"script": "pwd"}) # pyright: ignore[reportArgumentType]
+ _assert_error_observation(result, includes="active Runtime lease")
asyncio.run(scenario())
def test_shell_runtime_state_validates_offset_keys() -> None:
- state = DifyShellRuntimeState.model_validate(
+ state = State.model_validate(
{
"job_ids": ['job"bad with spaces'],
"job_offsets": {'job"bad with spaces': 0},
@@ -1201,7 +1029,7 @@ def test_shell_runtime_state_validates_offset_keys() -> None:
)
assert state.job_ids == ['job"bad with spaces']
with pytest.raises(ValueError, match="unknown job ids"):
- _ = DifyShellRuntimeState.model_validate(
+ _ = State.model_validate(
{
"job_ids": ["job-1"],
"job_offsets": {"job-2": 3},
@@ -1220,12 +1048,12 @@ def _layer_with_redaction(
config: DifyShellLayerConfig | None = None,
shell_redact_patterns: list[str] | None = None,
token_value: str = "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0.fake-long-jwe-token-value",
-) -> tuple[DifyShellLayer, FakeProvider]:
+) -> tuple[ShellSession, FakeLeaseFixture]:
"""Create a layer with agent_stub env injection and optional redaction patterns."""
layer, provider = _layer(commands=commands, config=config)
- layer.shell_redact_patterns = shell_redact_patterns or []
- layer.agent_stub_api_base_url = "http://localhost:5050/agent-stub"
- layer.agent_stub_token_factory = lambda execution_context, session_id: token_value
+ layer.deps.services.shell_redact_patterns = shell_redact_patterns or []
+ layer.deps.services.agent_stub_api_base_url = "http://localhost:5050/agent-stub"
+ layer.deps.services.agent_stub_token_factory = lambda execution_context, session_id: token_value
return layer, provider
@@ -1254,17 +1082,15 @@ def test_shell_run_issues_one_jwe_and_redaction_does_not_issue_another() -> None
commands = FakeCommands(run_handler=run_handler)
layer, _provider = _layer_with_redaction(commands=commands)
- layer.agent_stub_token_factory = token_factory
+ layer.deps.services.agent_stub_token_factory = token_factory
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
- tools = {tool.name: tool for tool in layer.tools}
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "env"}, None) # pyright: ignore[reportArgumentType]
- _, output = _parse_tagged_observation(result)
- assert issued_tokens[0] not in output
- assert "DIFY_AGENT_STUB_AUTH_JWE=***" in output
+ result = await layer._tool_run(**{"script": "env"}) # pyright: ignore[reportArgumentType]
+ _, output = _parse_tagged_observation(result)
+ assert issued_tokens[0] not in output
+ assert "DIFY_AGENT_STUB_AUTH_JWE=***" in output
asyncio.run(scenario())
assert issued_tokens == ["actual-long-jwe-token-1"]
@@ -1313,30 +1139,23 @@ def test_two_running_jobs_redact_and_clean_up_their_own_jwes_independently() ->
),
)
layer, _provider = _layer_with_redaction(commands=commands)
- layer.agent_stub_token_factory = token_factory
+ layer.deps.services.agent_stub_token_factory = token_factory
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
- tools = {tool.name: tool for tool in layer.tools}
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- await tools["shell_run"].function_schema.call({"script": "start first"}, None) # pyright: ignore[reportArgumentType]
- await tools["shell_run"].function_schema.call({"script": "start second"}, None) # pyright: ignore[reportArgumentType]
- assert issued_tokens == tokens
- assert layer._job_agent_stub_tokens == {"job-1": tokens[0], "job-2": tokens[1]}
-
- wait_result = await tools["shell_wait"].function_schema.call({"job_id": "job-1"}, None) # pyright: ignore[reportArgumentType]
- _, wait_output = _parse_tagged_observation(wait_result)
- assert wait_output == "wait=***\n"
- assert layer._job_agent_stub_tokens == {"job-2": tokens[1]}
-
- input_result = await tools["shell_input"].function_schema.call(
- {"job_id": "job-2", "text": "finish\n"},
- None, # pyright: ignore[reportArgumentType]
- )
- _, input_output = _parse_tagged_observation(input_result)
- assert input_output == "input=***\n"
- assert layer._job_agent_stub_tokens == {}
+ await layer._tool_run(**{"script": "start first"}) # pyright: ignore[reportArgumentType]
+ await layer._tool_run(**{"script": "start second"}) # pyright: ignore[reportArgumentType]
+ assert issued_tokens == tokens
+
+ wait_result = await layer._tool_wait(**{"job_id": "job-1"}) # pyright: ignore[reportArgumentType]
+ _, wait_output = _parse_tagged_observation(wait_result)
+ assert wait_output == "wait=***\n"
+
+ input_result = await layer._tool_input(**{"job_id": "job-2", "text": "finish\n"})
+ _, input_output = _parse_tagged_observation(input_result)
+ assert input_output == "input=***\n"
+ assert layer._job_agent_stub_tokens == {}
asyncio.run(scenario())
@@ -1363,15 +1182,13 @@ def test_redact_output_applies_server_level_patterns() -> None:
shell_redact_patterns=[r"sk-proj-[A-Za-z0-9]+"],
)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
- tools = {tool.name: tool for tool in layer.tools}
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "cat .env"}, None) # pyright: ignore[reportArgumentType]
- _, output = _parse_tagged_observation(result)
- assert "sk-proj-abc123xyz" not in output
- assert "api_key=***" in output
+ result = await layer._tool_run(**{"script": "cat .env"}) # pyright: ignore[reportArgumentType]
+ _, output = _parse_tagged_observation(result)
+ assert "sk-proj-abc123xyz" not in output
+ assert "api_key=***" in output
asyncio.run(scenario())
@@ -1396,15 +1213,13 @@ def test_redact_output_applies_per_agent_config_patterns() -> None:
config = DifyShellLayerConfig(redact_patterns=[r"ghp_[A-Za-z0-9]{36}"])
layer, _provider = _layer_with_redaction(commands=commands, config=config)
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
- tools = {tool.name: tool for tool in layer.tools}
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "echo $TOKEN"}, None) # pyright: ignore[reportArgumentType]
- _, output = _parse_tagged_observation(result)
- assert "ghp_" not in output
- assert "token: ***" in output
+ result = await layer._tool_run(**{"script": "echo $TOKEN"}) # pyright: ignore[reportArgumentType]
+ _, output = _parse_tagged_observation(result)
+ assert "ghp_" not in output
+ assert "token: ***" in output
asyncio.run(scenario())
@@ -1429,13 +1244,11 @@ def test_redact_output_skips_short_jwe_values() -> None:
# Token value is short — should NOT be redacted even if it appears in output.
layer, _provider = _layer_with_redaction(commands=commands, token_value="short")
_bind_execution_context(layer)
- layer.runtime_state = _runtime_state()
- tools = {tool.name: tool for tool in layer.tools}
+ layer.save_state(_runtime_state())
async def scenario() -> None:
- async with layer.resource_context():
- result = await tools["shell_run"].function_schema.call({"script": "echo hi"}, None) # pyright: ignore[reportArgumentType]
- _, output = _parse_tagged_observation(result)
- assert "short" in output
+ result = await layer._tool_run(**{"script": "echo hi"}) # pyright: ignore[reportArgumentType]
+ _, output = _parse_tagged_observation(result)
+ assert "short" in output
asyncio.run(scenario())
diff --git a/dify-agent/tests/local/dify_agent/layers/test_runtime_layer.py b/dify-agent/tests/local/dify_agent/layers/test_runtime_layer.py
deleted file mode 100644
index de6ed027b7a..00000000000
--- a/dify-agent/tests/local/dify_agent/layers/test_runtime_layer.py
+++ /dev/null
@@ -1,63 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import cast
-
-import pytest
-
-from dify_agent.layers.runtime import DifyRuntimeLayer, DifyRuntimeLayerConfig
-from dify_agent.runtime_backend import RuntimeLayout, RuntimeLease
-
-
-@dataclass(slots=True)
-class _Backend:
- lease: RuntimeLease
- acquired: list[str] = field(default_factory=list)
- released: list[RuntimeLease] = field(default_factory=list)
-
- async def acquire(self, binding_ref: str) -> RuntimeLease:
- self.acquired.append(binding_ref)
- return self.lease
-
- async def release(self, lease: RuntimeLease) -> None:
- self.released.append(lease)
-
-
-async def test_runtime_layer_acquires_and_releases_operation_scoped_lease() -> None:
- lease = cast(
- RuntimeLease,
- cast(
- object,
- type(
- "Lease",
- (),
- {
- "layout": RuntimeLayout(home_dir="/home/agent", workspace_dir="/workspace"),
- "commands": object(),
- },
- )(),
- ),
- )
- backend = _Backend(lease=lease)
- layer = DifyRuntimeLayer.from_config_with_backend(
- DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),
- backend=backend, # pyright: ignore[reportArgumentType]
- )
-
- async with layer.resource_context():
- assert layer.lease is lease
- await layer.on_context_create()
- await layer.on_context_suspend()
- await layer.on_context_delete()
-
- assert backend.acquired == ["binding-1"]
- assert backend.released == [lease]
- with pytest.raises(RuntimeError, match="resource_context"):
- _ = layer.lease
-
-
-def test_runtime_layer_config_contains_only_backend_binding_ref() -> None:
- config = DifyRuntimeLayerConfig(backend_binding_ref="binding-1")
-
- assert config.model_dump() == {"backend_binding_ref": "binding-1"}
diff --git a/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py b/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py
index 3c8927bd732..c975b8ef4c4 100644
--- a/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py
+++ b/dify-agent/tests/local/dify_agent/layers/user_prompt/test_layer.py
@@ -7,8 +7,8 @@ from pydantic import ValidationError
from pydantic_ai.messages import BinaryContent, ImageUrl
from dify_agent.layers.user_prompt import DifyUserPromptLayerConfig
-from dify_agent.layers.user_prompt.layer import DifyUserPromptLayer
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
+from dify_agent.layers.user_prompt.layer import Capability
+from tests.local.dify_agent.module_support import deps_for
@pytest.mark.parametrize("include_image", [False, True])
@@ -59,9 +59,9 @@ def test_user_prompt_layer_injects_file_locators(include_image: bool, download_t
],
}
)
- layer = DifyUserPromptLayer.from_config(DifyUserPromptLayerConfig.model_validate_json(config.model_dump_json()))
+ layer = _content(DifyUserPromptLayerConfig.model_validate_json(config.model_dump_json()))
- prompts = layer.user_prompts
+ prompts = layer
assert prompts[0] == (
"Inspect these files.\n"
@@ -72,9 +72,8 @@ def test_user_prompt_layer_injects_file_locators(include_image: bool, download_t
'{"transfer_method":"tool_file","reference":"dify-file-ref:tool-file-1"},'
'{"transfer_method":"datasource_file","reference":"dify-file-ref:datasource-file-1"}]'
)
- assert layer.config.text == "Inspect these files."
- assert "locators" not in layer.config.model_dump()
- assert layer.user_prompts == prompts
+ assert config.text == "Inspect these files."
+ assert "locators" not in config.model_dump()
assert len(prompts) == (2 if include_image else 1)
if include_image:
assert isinstance(prompts[1], ImageUrl)
@@ -103,13 +102,13 @@ def test_user_prompt_layer_rejects_invalid_locators(locator: dict[str, str]) ->
def test_user_prompt_layer_preserves_text_without_locators() -> None:
- layer = DifyUserPromptLayer.from_config(DifyUserPromptLayerConfig(text=" Original prompt.\n"))
+ layer = _content(DifyUserPromptLayerConfig(text=" Original prompt.\n"))
- assert layer.user_prompts == [" Original prompt.\n"]
+ assert layer == [" Original prompt.\n"]
def test_user_prompt_layer_restores_image_url_content() -> None:
- layer = DifyUserPromptLayer.from_config(
+ layer = _content(
DifyUserPromptLayerConfig.model_validate(
{
"text": "What is in this image?",
@@ -128,7 +127,7 @@ def test_user_prompt_layer_restores_image_url_content() -> None:
)
)
- prompts = layer.user_prompts
+ prompts = layer
assert prompts[0] == "What is in this image?"
assert isinstance(prompts[1], ImageUrl)
@@ -139,7 +138,7 @@ def test_user_prompt_layer_restores_image_url_content() -> None:
def test_user_prompt_layer_restores_inline_binary_content() -> None:
payload = base64.b64encode(b"image-bytes").decode()
- layer = DifyUserPromptLayer.from_config(
+ layer = _content(
DifyUserPromptLayerConfig.model_validate(
{
"text": "Describe it.",
@@ -157,7 +156,7 @@ def test_user_prompt_layer_restores_inline_binary_content() -> None:
)
)
- content = layer.user_prompts[1]
+ content = layer[1]
assert isinstance(content, BinaryContent)
assert content.data == b"image-bytes"
@@ -190,9 +189,5 @@ def test_user_prompt_file_requires_exactly_one_transport(file_payload: dict[str,
DifyUserPromptLayerConfig.model_validate({"text": "Describe it.", "files": [file_payload]})
-def test_default_compositor_registers_user_prompt_layer() -> None:
- provider = next(provider for provider in create_default_layer_providers() if provider.type_id == "dify.user_prompt")
-
- layer = provider.create_layer({"text": "Describe it."})
-
- assert isinstance(layer, DifyUserPromptLayer)
+def _content(config):
+ return Capability("user_prompt").build_user_content(deps_for("user_prompt", config))
diff --git a/dify-agent/tests/local/dify_agent/module_support.py b/dify-agent/tests/local/dify_agent/module_support.py
new file mode 100644
index 00000000000..18f7f8fa8d6
--- /dev/null
+++ b/dify-agent/tests/local/dify_agent/module_support.py
@@ -0,0 +1,35 @@
+"""Data builders for module behavior tests; no legacy runtime is emulated."""
+
+import httpx
+from pydantic import BaseModel
+from dify_agent.runtime.context import Deps, Services
+
+
+def deps_for(name: str, config: BaseModel | dict, state: dict | None = None) -> Deps:
+ return Deps(
+ layers={
+ name: {
+ "config": config.model_dump(mode="json") if isinstance(config, BaseModel) else config,
+ "state": state or {},
+ }
+ },
+ services=Services(httpx.AsyncClient(), httpx.AsyncClient()),
+ run_id="test",
+ )
+
+
+async def invoke_native_tool(deps, toolset, name, arguments, *, inspect=None):
+ """Exercise schema preparation, validation and invocation in the real Agent."""
+ from pydantic_ai import Agent
+ from pydantic_ai.messages import ModelRequest, ModelResponse, ToolReturnPart, ToolCallPart, TextPart
+ from pydantic_ai.models.function import FunctionModel
+
+ async def model(messages, info):
+ if inspect is not None:
+ inspect(info)
+ returns = [p for m in messages if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, ToolReturnPart)]
+ if not returns:
+ return ModelResponse(parts=[ToolCallPart(name, arguments, tool_call_id="call")])
+ return ModelResponse(parts=[TextPart(str(returns[-1].content))])
+
+ return await Agent(FunctionModel(model), deps_type=Deps, toolsets=[toolset]).run("Use the tool", deps=deps)
diff --git a/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py b/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py
index d04611449eb..1aafd7e718a 100644
--- a/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py
+++ b/dify-agent/tests/local/dify_agent/protocol/test_protocol_schemas.py
@@ -4,41 +4,22 @@ import pytest
from pydantic import ValidationError
from pydantic_ai.messages import FinalResultEvent
-from agenton.compositor import CompositorSessionSnapshot
-from agenton.layers import ExitIntent
-from agenton_collections.layers.plain import PLAIN_PROMPT_LAYER_TYPE_ID, PromptLayerConfig
+from dify_agent.protocol.snapshot import SessionSnapshot
import dify_agent.protocol as protocol_exports
-from dify_agent.layers.ask_human import DifyAskHumanLayerConfig
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.dify_plugin import DIFY_PLUGIN_LLM_LAYER_TYPE_ID, DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID
from dify_agent.protocol.schemas import (
AgentRunUsage,
RUN_EVENT_ADAPTER,
CreateRunRequest,
- DeferredToolCallPayload,
- LayerExitSignals,
PydanticAIStreamRunEvent,
RunCancelledEvent,
RunCancelledEventData,
- RunComposition,
RunFailedEvent,
RunFailedEventData,
RunFailureType,
- RunLayerSpec,
RunStartedEvent,
RunSucceededEvent,
RunSucceededEventData,
- normalize_composition,
-)
-from dify_agent.layers.dify_plugin.configs import (
- DifyPluginLLMLayerConfig,
- DifyPluginToolConfig,
- DifyPluginToolParameter,
- DifyPluginToolParameterForm,
- DifyPluginToolParameterType,
- DifyPluginToolsLayerConfig,
)
@@ -54,19 +35,7 @@ def test_run_event_adapter_round_trips_typed_variants() -> None:
run_id="run-1",
data=RunSucceededEventData(
output={"answer": ["done"]},
- session_snapshot=CompositorSessionSnapshot(layers=[]),
- ),
- ),
- RunSucceededEvent(
- run_id="run-2",
- data=RunSucceededEventData(
- deferred_tool_call=DeferredToolCallPayload(
- tool_call_id="tool-call-1",
- tool_name="ask_human",
- args={"question": "Need approval"},
- metadata={"layer_type": "dify.ask_human"},
- ),
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
),
RunFailedEvent(
@@ -120,7 +89,7 @@ def test_run_failed_event_error_type_is_optional_and_round_trips() -> None:
@pytest.mark.parametrize("event_type", ["run_failed", "run_cancelled"])
def test_non_success_terminal_event_round_trips_optional_snapshot(event_type: str) -> None:
- snapshot = CompositorSessionSnapshot(layers=[])
+ snapshot = SessionSnapshot(layers={})
event: RunFailedEvent | RunCancelledEvent
if event_type == "run_failed":
event = RunFailedEvent(
@@ -169,293 +138,15 @@ def test_protocol_package_no_longer_exports_execution_context_dto() -> None:
assert not hasattr(protocol_exports, "RunPurpose")
-def test_create_run_request_accepts_dto_first_public_composition_and_normalizes_graph_config() -> None:
- prompt_config = PromptLayerConfig(prefix="system", user="hello")
- execution_context_config = DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- workflow_id="workflow-1",
- workflow_run_id="workflow-run-1",
- node_id="node-1",
- node_execution_id="node-execution-1",
- agent_mode="workflow_run",
- invoke_from="service-api",
- trace_id="trace-1",
- )
- llm_config = DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- )
- output_config = DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {"title": {"type": "string"}},
- "required": ["title"],
- "additionalProperties": False,
- }
- )
- request = CreateRunRequest(
- idempotency_key="workflow-run-1:node-execution-1",
- metadata={"source": "unit_test"},
- composition=RunComposition(
- layers=[
- RunLayerSpec(name="prompt", type=PLAIN_PROMPT_LAYER_TYPE_ID, config=prompt_config),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=execution_context_config,
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type=DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=llm_config,
- ),
- RunLayerSpec(
- name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=output_config,
- ),
- ]
- ),
- )
-
- graph_config, layer_configs = normalize_composition(request.composition)
- payload = request.model_dump(mode="json")
-
- assert payload["composition"]["layers"][1]["config"] == {
- "tenant_id": "tenant-1",
- "user_id": None,
- "user_from": "account",
- "app_id": None,
- "workflow_id": "workflow-1",
- "workflow_run_id": "workflow-run-1",
- "node_id": "node-1",
- "node_execution_id": "node-execution-1",
- "conversation_id": None,
- "agent_id": None,
- "agent_config_version_id": None,
- "agent_config_version_kind": None,
- "agent_mode": "workflow_run",
- "invoke_from": "service-api",
- "trace_id": "trace-1",
- }
- assert payload["idempotency_key"] == "workflow-run-1:node-execution-1"
- assert payload["metadata"] == {"source": "unit_test"}
- assert payload["composition"]["layers"][0]["config"] == {"prefix": "system", "user": "hello", "suffix": []}
- assert [layer.model_dump(mode="json") for layer in graph_config.layers] == [
- {"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "deps": {}, "metadata": {}},
- {
- "name": "execution_context",
- "type": DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- "deps": {},
- "metadata": {},
- },
- {
- "name": DIFY_AGENT_MODEL_LAYER_ID,
- "type": DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- "deps": {"execution_context": "execution_context"},
- "metadata": {},
- },
- {
- "name": DIFY_AGENT_OUTPUT_LAYER_ID,
- "type": DIFY_OUTPUT_LAYER_TYPE_ID,
- "deps": {},
- "metadata": {},
- },
- ]
- assert layer_configs == {
- "prompt": prompt_config,
- "execution_context": execution_context_config,
- DIFY_AGENT_MODEL_LAYER_ID: llm_config,
- DIFY_AGENT_OUTPUT_LAYER_ID: output_config,
- }
-
-
-def test_create_run_request_accepts_deferred_tool_results_payload() -> None:
- request = CreateRunRequest.model_validate(
- {
- "composition": {
- "layers": [
- {"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "config": {"user": "hello"}},
- {"name": "ask_human", "type": "dify.ask_human", "config": DifyAskHumanLayerConfig().model_dump()},
- ]
- },
- "deferred_tool_results": {
- "calls": {
- "tool-call-1": {
- "status": "submitted",
- "action": {"id": "submit", "label": "Submit"},
- "values": {"comment": "Looks good."},
- }
- }
- },
- }
- )
-
- assert request.deferred_tool_results is not None
- assert request.deferred_tool_results.calls["tool-call-1"] == {
- "status": "submitted",
- "action": {"id": "submit", "label": "Submit"},
- "values": {"comment": "Looks good."},
- }
-
-
-def test_create_run_request_accepts_plugin_tools_layer_with_prepared_parameters_and_schema() -> None:
- request = CreateRunRequest.model_validate(
- {
- "composition": {
- "layers": [
- {"name": "prompt", "type": PLAIN_PROMPT_LAYER_TYPE_ID, "config": {"user": "hello"}},
- {
- "name": "execution_context",
- "type": DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- "config": {
- "tenant_id": "tenant-1",
- "user_from": "account",
- "agent_mode": "workflow_run",
- "invoke_from": "service-api",
- },
- },
- {
- "name": DIFY_AGENT_MODEL_LAYER_ID,
- "type": DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- "deps": {"execution_context": "execution_context"},
- "config": {
- "plugin_id": "langgenius/openai",
- "model_provider": "openai",
- "model": "demo-model",
- "credentials": {"api_key": "secret"},
- },
- },
- {
- "name": "tools",
- "type": DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- "deps": {"execution_context": "execution_context"},
- "config": {
- "tools": [
- {
- "plugin_id": "langgenius/search",
- "provider": "search",
- "tool_name": "web_search",
- "credential_type": "api-key",
- "runtime_parameters": {"site": "docs.dify.ai"},
- "parameters": [
- {
- "name": "query",
- "type": "string",
- "form": "llm",
- "required": True,
- "llm_description": "Search query",
- },
- {
- "name": "site",
- "type": "string",
- "form": "form",
- "required": True,
- "llm_description": "Hidden site",
- },
- ],
- "parameters_json_schema": {
- "type": "object",
- "properties": {"query": {"type": "string", "description": "Search query"}},
- "required": ["query"],
- },
- }
- ]
- },
- },
- ]
- }
- }
- )
-
- graph_config, layer_configs = normalize_composition(request.composition)
-
- assert [layer.type for layer in graph_config.layers] == [
- PLAIN_PROMPT_LAYER_TYPE_ID,
- DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- DIFY_PLUGIN_LLM_LAYER_TYPE_ID,
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- ]
- assert DifyPluginToolsLayerConfig.model_validate(layer_configs["tools"]) == DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/search",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- runtime_parameters={"site": "docs.dify.ai"},
- parameters=[
- DifyPluginToolParameter(
- name="query",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Search query",
- ),
- DifyPluginToolParameter(
- name="site",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.FORM,
- required=True,
- llm_description="Hidden site",
- ),
- ],
- parameters_json_schema={
- "type": "object",
- "properties": {"query": {"type": "string", "description": "Search query"}},
- "required": ["query"],
- },
- )
- ]
- )
-
-
-def test_on_exit_default_to_suspend_and_are_public() -> None:
- assert protocol_exports.LayerExitSignals is LayerExitSignals
- assert protocol_exports.RunComposition is RunComposition
- assert protocol_exports.RunLayerSpec is RunLayerSpec
- assert protocol_exports.normalize_composition is normalize_composition
- assert protocol_exports.DIFY_AGENT_OUTPUT_LAYER_ID == DIFY_AGENT_OUTPUT_LAYER_ID
- request = CreateRunRequest.model_validate({"composition": {"layers": []}})
-
- assert request.on_exit.default is ExitIntent.SUSPEND
- assert request.on_exit.layers == {}
-
-
-def test_run_succeeded_event_data_requires_exactly_one_result_variant() -> None:
- snapshot = CompositorSessionSnapshot(layers=[])
-
- with pytest.raises(ValidationError, match="Exactly one of output or deferred_tool_call must be set"):
- _ = RunSucceededEventData(session_snapshot=snapshot)
-
- with pytest.raises(ValidationError, match="Exactly one of output or deferred_tool_call must be set"):
- _ = RunSucceededEventData(
- output="done",
- deferred_tool_call=DeferredToolCallPayload(
- tool_call_id="tool-call-1",
- tool_name="ask_human",
- args={"question": "Need approval"},
- ),
- session_snapshot=snapshot,
- )
-
-
-def test_run_succeeded_event_data_allows_explicit_json_null_output() -> None:
- snapshot = CompositorSessionSnapshot(layers=[])
-
- data = RunSucceededEventData(output=None, session_snapshot=snapshot)
-
- assert data.output is None
- assert data.deferred_tool_call is None
+def test_run_succeeded_event_data_requires_output() -> None:
+ with pytest.raises(ValidationError, match="output"):
+ RunSucceededEventData(session_snapshot=SessionSnapshot())
def test_run_succeeded_event_round_trips_explicit_json_null_output() -> None:
event = RunSucceededEvent(
run_id="run-null-output",
- data=RunSucceededEventData(output=None, session_snapshot=CompositorSessionSnapshot(layers=[])),
+ data=RunSucceededEventData(output=None, session_snapshot=SessionSnapshot(layers={})),
)
payload = RUN_EVENT_ADAPTER.dump_json(event)
@@ -463,7 +154,6 @@ def test_run_succeeded_event_round_trips_explicit_json_null_output() -> None:
assert isinstance(decoded, RunSucceededEvent)
assert decoded.data.output is None
- assert decoded.data.deferred_tool_call is None
assert b'"output":null' in payload
assert b'"deferred_tool_call"' not in payload
@@ -473,7 +163,7 @@ def test_run_succeeded_event_round_trips_usage() -> None:
run_id="run-usage",
data=RunSucceededEventData(
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
usage=AgentRunUsage(prompt_tokens=3, completion_tokens=5),
),
)
@@ -525,7 +215,7 @@ def test_run_succeeded_event_round_trips_complete_pricing_usage() -> None:
run_id="run-priced-usage",
data=RunSucceededEventData(
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
usage=AgentRunUsage(
prompt_tokens=10,
prompt_unit_price=Decimal("5"),
@@ -559,21 +249,6 @@ def test_run_succeeded_event_round_trips_complete_pricing_usage() -> None:
assert decoded.data.usage.time_to_generate == 0.3
-def test_on_exit_accept_layer_overrides() -> None:
- request = CreateRunRequest.model_validate(
- {
- "composition": {"layers": []},
- "on_exit": {
- "default": "delete",
- "layers": {"prompt": "suspend", "llm": "delete"},
- },
- }
- )
-
- assert request.on_exit.default is ExitIntent.DELETE
- assert request.on_exit.layers == {"prompt": ExitIntent.SUSPEND, "llm": ExitIntent.DELETE}
-
-
def test_create_run_request_rejects_removed_top_level_execution_context() -> None:
with pytest.raises(ValidationError):
_ = CreateRunRequest.model_validate(
@@ -599,11 +274,6 @@ def test_create_run_request_rejects_removed_top_level_purpose() -> None:
)
-def test_layer_exit_signals_reject_extra_fields() -> None:
- with pytest.raises(ValidationError):
- _ = LayerExitSignals.model_validate({"default": "suspend", "unknown": "value"})
-
-
@pytest.mark.parametrize("event_type", ["agent_output", "session_snapshot"])
def test_removed_non_terminal_payload_events_are_rejected(event_type: str) -> None:
with pytest.raises(ValidationError):
diff --git a/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py b/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py
index 3a20a40e766..751005137b7 100644
--- a/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py
+++ b/dify-agent/tests/local/dify_agent/runtime/test_agent_observability.py
@@ -21,6 +21,8 @@ from pydantic_ai.models.test import TestModel
import dify_agent.server.observability as server_observability
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
+from pydantic_ai.toolsets import FunctionToolset
+
from dify_agent.runtime.agent_factory import DIFY_AGENT_RUN_NAME, create_agent
from dify_agent.runtime.observability import (
DIFY_TENANT_ID_ATTRIBUTE,
@@ -80,7 +82,9 @@ def test_create_agent_instrument_disabled_survives_global_instrument_all() -> No
try:
Agent.instrument_all(InstrumentationSettings(tracer_provider=platform_provider))
- agent = create_agent(TestModel(custom_output_text="done"), tools=[])
+ agent = create_agent(
+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]
+ )
assert agent.instrument is False
_ = agent.run_sync("test-only input")
@@ -99,7 +103,11 @@ def test_agent_observability_runs_agent_spans_to_business_exporter_only() -> Non
try:
Agent.instrument_all(InstrumentationSettings(tracer_provider=platform_provider))
observability = AgentObservability(client=client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
_ = agent.run_sync("test-only input")
@@ -125,7 +133,11 @@ def test_agent_observability_excludes_content_by_default() -> None:
client = _local_client(exporter)
try:
observability = AgentObservability(client=client, include_content=False)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
_ = agent.run_sync("content-sentinel-input-1")
@@ -145,7 +157,11 @@ def test_agent_observability_includes_content_when_opted_in() -> None:
client = _local_client(exporter)
try:
observability = AgentObservability(client=client, include_content=True)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
_ = agent.run_sync("content-sentinel-input-2")
@@ -166,7 +182,11 @@ def test_business_agent_root_detaches_from_platform_parent_span() -> None:
business_client = _local_client(business_exporter)
try:
observability = AgentObservability(client=business_client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
with platform_client.span("platform-incoming-request"):
@@ -194,7 +214,9 @@ def test_agent_shutdown_does_not_stop_platform_pipeline() -> None:
try:
Agent.instrument_all(InstrumentationSettings(tracer_provider=platform_client.config.get_tracer_provider()))
observability = AgentObservability(client=business_client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[])
+ agent = create_agent(
+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]
+ )
observability.instrument(agent)
_ = agent.run_sync("test-only input")
assert business_client.force_flush(timeout_millis=10000)
@@ -234,7 +256,11 @@ def test_business_descendants_stay_in_business_trace_and_caller_context_restored
business_client = _local_client(business_exporter)
try:
observability = AgentObservability(client=business_client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
with platform_client.span("platform-incoming-request") as platform_span:
@@ -278,7 +304,9 @@ def test_platform_httpx_client_span_detaches_from_business_parent() -> None:
return http.get("http://test-only.local/ping").text
observability = AgentObservability(client=business_client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(net_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[Tool(net_tool)])], capabilities=[]
+ )
observability.instrument(agent)
with platform_client.span("platform-incoming-request"):
@@ -406,7 +434,11 @@ def test_concurrent_agent_runs_have_independent_business_roots() -> None:
observability = AgentObservability(client=business_client)
agents = []
for index in range(2):
- agent = create_agent(TestModel(custom_output_text=f"done-{index}"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text=f"done-{index}"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
agents.append(agent)
@@ -494,7 +526,9 @@ def test_shared_trace_context_mode_links_business_run_to_platform_parent() -> No
return http.get("http://test-only.local/ping").text
observability = AgentObservability(client=business_client, trace_context_mode="shared")
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(net_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[Tool(net_tool)])], capabilities=[]
+ )
observability.instrument(agent)
with platform_client.span("shared-platform-root"):
@@ -546,7 +580,11 @@ def test_shared_mode_agent_pipeline_respects_remote_parent_sampling(monkeypatch:
observability_instance = server_observability.configure_agent_observability(settings)
assert observability_instance is not None
try:
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability_instance.instrument(agent)
unsampled = set_span_in_context(
@@ -654,7 +692,11 @@ def test_agent_observability_stamps_dify_context_on_every_run_span(trace_context
client=client,
trace_context_mode=cast(Literal["isolated", "shared"], trace_context_mode),
)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent, execution_context=_workflow_execution_context())
_ = agent.run_sync("test-only input")
@@ -677,7 +719,11 @@ def test_agent_observability_omits_dify_attributes_without_an_execution_context(
client = _local_client(exporter)
try:
observability = AgentObservability(client=client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent)
_ = agent.run_sync("test-only input")
@@ -700,7 +746,11 @@ def test_dify_attributes_do_not_break_isolated_parent_policy() -> None:
business_client = _local_client(business_exporter)
try:
observability = AgentObservability(client=business_client)
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
observability.instrument(agent, execution_context=_workflow_execution_context())
with platform_client.span("platform-incoming-request"):
diff --git a/dify-agent/tests/local/dify_agent/runtime/test_compositor_factory.py b/dify-agent/tests/local/dify_agent/runtime/test_compositor_factory.py
deleted file mode 100644
index d79e615b73e..00000000000
--- a/dify-agent/tests/local/dify_agent/runtime/test_compositor_factory.py
+++ /dev/null
@@ -1,189 +0,0 @@
-import sys
-import types
-from typing import cast
-
-if "graphon.model_runtime.entities.llm_entities" not in sys.modules:
- graphon_module = types.ModuleType("graphon")
- model_runtime_module = types.ModuleType("graphon.model_runtime")
- entities_module = types.ModuleType("graphon.model_runtime.entities")
- llm_entities_module = types.ModuleType("graphon.model_runtime.entities.llm_entities")
- message_entities_module = types.ModuleType("graphon.model_runtime.entities.message_entities")
-
- setattr(llm_entities_module, "LLMResultChunk", type("LLMResultChunk", (), {}))
- setattr(llm_entities_module, "LLMUsage", type("LLMUsage", (), {}))
-
- for name in (
- "AssistantPromptMessage",
- "AudioPromptMessageContent",
- "DocumentPromptMessageContent",
- "ImagePromptMessageContent",
- "PromptMessage",
- "PromptMessageContentUnionTypes",
- "PromptMessageTool",
- "SystemPromptMessage",
- "TextPromptMessageContent",
- "ToolPromptMessage",
- "UserPromptMessage",
- "VideoPromptMessageContent",
- ):
- setattr(message_entities_module, name, type(name, (), {}))
-
- sys.modules["graphon"] = graphon_module
- sys.modules["graphon.model_runtime"] = model_runtime_module
- sys.modules["graphon.model_runtime.entities"] = entities_module
- sys.modules["graphon.model_runtime.entities.llm_entities"] = llm_entities_module
- sys.modules["graphon.model_runtime.entities.message_entities"] = message_entities_module
-
- setattr(graphon_module, "model_runtime", model_runtime_module)
- setattr(model_runtime_module, "entities", entities_module)
- setattr(entities_module, "llm_entities", llm_entities_module)
- setattr(entities_module, "message_entities", message_entities_module)
-
-if "jsonschema" not in sys.modules:
- jsonschema_module = types.ModuleType("jsonschema")
- jsonschema_exceptions_module = types.ModuleType("jsonschema.exceptions")
- jsonschema_protocols_module = types.ModuleType("jsonschema.protocols")
- jsonschema_validators_module = types.ModuleType("jsonschema.validators")
-
- class _SchemaError(Exception):
- pass
-
- class _ValidationError(Exception):
- path: tuple[object, ...] = ()
-
- class _Validator:
- @staticmethod
- def check_schema(schema):
- return None
-
- def __init__(self, schema):
- self.schema = schema
-
- def iter_errors(self, value):
- return iter(())
-
- def _validator_for(schema):
- return _Validator
-
- setattr(jsonschema_module, "SchemaError", _SchemaError)
- setattr(jsonschema_exceptions_module, "ValidationError", _ValidationError)
- setattr(jsonschema_protocols_module, "Validator", _Validator)
- setattr(jsonschema_validators_module, "validator_for", _validator_for)
-
- sys.modules["jsonschema"] = jsonschema_module
- sys.modules["jsonschema.exceptions"] = jsonschema_exceptions_module
- sys.modules["jsonschema.protocols"] = jsonschema_protocols_module
- sys.modules["jsonschema.validators"] = jsonschema_validators_module
-
-from dify_agent.layers.config import DIFY_CONFIG_LAYER_TYPE_ID, DifyConfigLayerConfig
-from dify_agent.layers.config.layer import DifyConfigLayer
-from dify_agent.layers.dify_core_tools import DIFY_CORE_TOOLS_LAYER_TYPE_ID, DifyCoreToolsLayerConfig
-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer
-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
-from dify_agent.layers.runtime.layer import DifyRuntimeLayer
-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
-from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.shell.layer import DifyShellLayer
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
-from dify_agent.runtime_backend import ExecutionBindingBackend, HomeSnapshotBackend, RuntimeBackendProfile
-
-
-class FakeProvider:
- """No-op provider for tests that never actually open a shell resource."""
-
- async def create(self) -> object:
- raise AssertionError("create should not be called by these tests")
-
-
-def _runtime_backend_profile() -> RuntimeBackendProfile:
- return RuntimeBackendProfile(
- home_snapshots=cast(HomeSnapshotBackend, cast(object, FakeProvider())),
- execution_bindings=cast(ExecutionBindingBackend, cast(object, FakeProvider())),
- )
-
-
-def test_default_layer_providers_register_config_layer() -> None:
- providers = create_default_layer_providers()
-
- config_provider = next(provider for provider in providers if provider.type_id == DIFY_CONFIG_LAYER_TYPE_ID)
- config = DifyConfigLayerConfig(agent_id="agent-1")
- layer = config_provider.create_layer(config)
-
- assert isinstance(layer, DifyConfigLayer)
- assert layer.type_id == DIFY_CONFIG_LAYER_TYPE_ID
- assert layer.config == config
-
-
-def test_default_layer_providers_register_runtime_layer() -> None:
- profile = _runtime_backend_profile()
-
- providers = create_default_layer_providers(
- runtime_backend_profile=profile,
- )
- shell_provider = next(provider for provider in providers if provider.type_id == DIFY_SHELL_LAYER_TYPE_ID)
- shell_layer = shell_provider.create_layer(DifyShellLayerConfig())
- runtime_provider = next(provider for provider in providers if provider.type_id == DIFY_RUNTIME_LAYER_TYPE_ID)
- runtime_layer = runtime_provider.create_layer(DifyRuntimeLayerConfig(backend_binding_ref="binding-1"))
-
- assert isinstance(shell_layer, DifyShellLayer)
- assert isinstance(runtime_layer, DifyRuntimeLayer)
- assert runtime_layer.backend is profile.execution_bindings
- assert {provider.type_id for provider in providers} >= {"dify.runtime", "dify.shell"}
-
-
-def test_default_layer_providers_forward_agent_stub_token_factory() -> None:
- captured_calls: list[tuple[DifyExecutionContextLayerConfig, str | None]] = []
-
- def build_agent_stub_token(
- execution_context: DifyExecutionContextLayerConfig,
- *,
- session_id: str | None,
- ) -> str:
- captured_calls.append((execution_context, session_id))
- return f"token-for:{execution_context.tenant_id}:{session_id}"
-
- providers = create_default_layer_providers(
- runtime_backend_profile=_runtime_backend_profile(),
- agent_stub_api_base_url="https://agent.example.com/agent-stub",
- agent_stub_token_factory=build_agent_stub_token,
- )
- shell_provider = next(provider for provider in providers if provider.type_id == DIFY_SHELL_LAYER_TYPE_ID)
- shell_layer = shell_provider.create_layer(DifyShellLayerConfig())
-
- token = shell_layer.agent_stub_token_factory(
- DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- session_id="abc12ff",
- )
-
- assert token == "token-for:tenant-1:abc12ff"
- assert captured_calls == [
- (
- DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- "abc12ff",
- )
- ]
-
-
-def test_default_layer_providers_register_core_tools_layer() -> None:
- providers = create_default_layer_providers(inner_api_url="http://dify-api", inner_api_key="inner-secret")
-
- core_provider = next(provider for provider in providers if provider.type_id == DIFY_CORE_TOOLS_LAYER_TYPE_ID)
- layer = core_provider.create_layer(DifyCoreToolsLayerConfig())
-
- assert isinstance(layer, DifyCoreToolsLayer)
- assert layer.type_id == DIFY_CORE_TOOLS_LAYER_TYPE_ID
- assert layer.inner_api_url == "http://dify-api"
- assert layer.inner_api_key == "inner-secret"
- assert layer.config == DifyCoreToolsLayerConfig()
diff --git a/dify-agent/tests/local/dify_agent/runtime/test_modules.py b/dify-agent/tests/local/dify_agent/runtime/test_modules.py
new file mode 100644
index 00000000000..b54bc6c5dab
--- /dev/null
+++ b/dify-agent/tests/local/dify_agent/runtime/test_modules.py
@@ -0,0 +1,211 @@
+"""Native module contracts: canonical JSON data, references and data migration."""
+
+from types import ModuleType
+
+import httpx
+import pytest
+from pydantic import ValidationError
+from pydantic_ai.capabilities import AbstractCapability
+from pydantic_ai.messages import ModelRequest, UserPromptPart
+from pydantic_ai.toolsets import AbstractToolset
+
+from dify_agent.layers import history
+from dify_agent.layers.prompt import layer as prompt
+from dify_agent.protocol.schemas import CreateRunRequest, RunComposition, RunLayerSpec
+from dify_agent.protocol.snapshot import SessionSnapshot
+from dify_agent.runtime.context import Services
+from dify_agent.runtime.modules import REGISTRY, create_modules, load_modules, snapshot_modules
+
+
+def services():
+ return Services(httpx.AsyncClient(), httpx.AsyncClient())
+
+
+def request(*extra: RunLayerSpec, snapshot: SessionSnapshot | None = None) -> CreateRunRequest:
+ return CreateRunRequest(
+ composition=RunComposition(
+ layers=[
+ RunLayerSpec(
+ name="execution_context",
+ config={"tenant_id": "tenant", "agent_mode": "agent_app", "invoke_from": "web-app"},
+ ),
+ RunLayerSpec(name="llm", config={"plugin_id": "openai", "model_provider": "openai", "model": "demo"}),
+ *extra,
+ ]
+ ),
+ session_snapshot=snapshot,
+ )
+
+
+def test_all_registered_modules_export_native_components(services):
+ for module in set(REGISTRY.values()):
+ assert hasattr(module, "Config") and hasattr(module, "State")
+ assert hasattr(module, "Capability") != hasattr(module, "Toolset")
+ implementation = module.Capability if hasattr(module, "Capability") else module.Toolset
+ native = AbstractCapability if hasattr(module, "Capability") else AbstractToolset
+ assert issubclass(implementation, native)
+
+
+def test_one_module_registered_twice_has_independent_json_and_fresh_instances(services):
+ registry = {**REGISTRY, "first": prompt, "second": prompt}
+ incoming = request(
+ RunLayerSpec(name="first", config={"user": "first"}),
+ RunLayerSpec(name="second", config={"user": "second"}),
+ RunLayerSpec(name="history"),
+ )
+ a = load_modules(incoming, services, "a", registry=registry)
+ b = load_modules(incoming, services, "b", registry=registry)
+ assert a.layers["first"]["config"]["user"] == "first"
+ assert a.layers["second"]["config"]["user"] == "second"
+ a.layers["first"]["config"]["user"] = "changed"
+ assert b.layers["first"]["config"]["user"] == "first"
+ assert incoming.composition.layers[2].config["user"] == "first"
+ assert create_modules(a, registry=registry)["first"] is not create_modules(b, registry=registry)["first"]
+ assert "config" not in snapshot_modules(a, registry=registry).layers["history"]
+
+
+def test_state_requires_explicit_json_writeback(services):
+ incoming = request(RunLayerSpec(name="history"))
+ deps = load_modules(incoming, services, "test")
+ parsed = history.State.model_validate(deps.layers["history"]["state"])
+ parsed.messages.append(ModelRequest(parts=[UserPromptPart(content="saved")]))
+ assert deps.layers["history"]["state"]["messages"] == []
+ deps.layers["history"]["state"] = parsed.model_dump(mode="json")
+ # Persistence uses the module-owned dump, independent of current config.
+ snap = snapshot_modules(deps)
+ again = load_modules(request(RunLayerSpec(name="history"), snapshot=snap), services, "again")
+ again.layers["history"]["state"]["messages"].append({"kind": "request", "parts": []})
+ assert len(snap.layers["history"]["messages"]) == 1
+ assert history.State.model_validate(snap.layers["history"]).messages == parsed.messages
+
+
+ "spec,error",
+ [
+ (RunLayerSpec(name="unknown"), "Unknown registered module"),
+ (RunLayerSpec(name="llm"), "unique"),
+ (RunLayerSpec(name="tools", config={"execution_context": "missing"}), "reference execution_context"),
+ (RunLayerSpec(name="shell", config={"runtime": "execution_context"}), "reference runtime"),
+ ],
+)
+def test_invalid_module_or_reference_is_rejected_before_io(spec, error, services):
+ with pytest.raises(ValueError, match=error):
+ load_modules(request(spec), services, "test")
+
+
+def test_snapshot_uses_current_config_and_drops_removed_optional_slots(services):
+ incoming = request(
+ RunLayerSpec(name="prompt", config={"user": "current"}),
+ snapshot=SessionSnapshot(layers={"prompt": {}, "tools": {}}),
+ )
+ deps = load_modules(incoming, services, "test")
+ assert deps.layers["prompt"]["config"]["user"] == "current"
+ assert "tools" not in snapshot_modules(deps).layers
+ with pytest.raises(ValueError, match="Unknown snapshot modules"):
+ load_modules(request(snapshot=SessionSnapshot(layers={"unregistered": {}})), services, "bad")
+
+
+def test_legacy_snapshot_conversion_preserves_only_retained_state():
+ snapshot = SessionSnapshot.model_validate(
+ {
+ "schema_version": 1,
+ "layers": [
+ {"name": "shell", "lifecycle_state": "suspended", "runtime_state": {"job_ids": [], "job_offsets": {}}},
+ {
+ "name": "config",
+ "lifecycle_state": "new",
+ "runtime_state": {
+ "pulled_skill_outputs": {"skill": "content"},
+ "config_context_json": "obsolete manifest",
+ "config_cli_help": {"config": "obsolete help"},
+ "push_spec_json_schema": "obsolete",
+ },
+ },
+ {"name": "history", "lifecycle_state": "suspended", "runtime_state": {"messages": []}},
+ {"name": "ask_human", "lifecycle_state": "suspended", "runtime_state": {"pending": "obsolete"}},
+ ],
+ }
+ )
+ assert snapshot.schema_version == 2
+ assert snapshot.layers["shell"]["initialized"] is True
+ assert snapshot.layers["config"] == {"initialized": False, "pulled_skill_outputs": {"skill": "content"}}
+ assert snapshot.layers["history"] == {"messages": []}
+ assert "ask_human" not in snapshot.layers
+ assert SessionSnapshot.model_validate_json(snapshot.model_dump_json()) == snapshot
+
+
+ "slot",
+ [
+ {"name": "custom", "lifecycle_state": "suspended", "runtime_state": {}},
+ {"name": "shell", "lifecycle_state": "active", "runtime_state": {}},
+ {"name": "shell", "lifecycle_state": "suspended", "runtime_state": None},
+ ],
+)
+def test_invalid_legacy_state_is_rejected(slot):
+ with pytest.raises(ValidationError):
+ SessionSnapshot.model_validate({"schema_version": 1, "layers": [slot]})
+
+
+def test_duplicate_removed_legacy_slots_are_rejected():
+ slot = {"name": "ask_human", "lifecycle_state": "suspended", "runtime_state": {}}
+ with pytest.raises(ValidationError, match="Duplicate"):
+ SessionSnapshot.model_validate({"schema_version": 1, "layers": [slot, slot]})
+
+
+async def test_native_sequential_tools_commit_json_state_without_lost_updates():
+ import asyncio
+ from pydantic import BaseModel
+ from pydantic_ai import Agent, RunContext
+ from pydantic_ai.messages import ModelRequest, ModelResponse, TextPart, ToolCallPart, ToolReturnPart
+ from pydantic_ai.models.function import FunctionModel
+ from pydantic_ai.toolsets import FunctionToolset
+ from dify_agent.runtime.context import Deps
+
+ class Config(BaseModel):
+ pass
+
+ class State(BaseModel):
+ count: int = 0
+
+ class Toolset(FunctionToolset[Deps]):
+ def __init__(self, name):
+ super().__init__(id=name, sequential=True)
+ self.name = name
+
+ @self.tool
+ async def increment(ctx: RunContext[Deps]) -> int:
+ """Persist one increment across an async operation."""
+ data = ctx.deps.layers[self.name]
+ state = State.model_validate(data["state"])
+ await asyncio.sleep(0)
+ state.count += 1
+ data["state"] = state.model_dump(mode="json")
+ return state.count
+
+ module = ModuleType("counter")
+ module.Config = Config
+ module.State = State
+ module.Toolset = Toolset
+ registry = {**REGISTRY, "counter": module}
+
+ async def model(messages, info):
+ parts = [p for m in messages if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, ToolReturnPart)]
+ if not parts:
+ assert info.function_tools[0].sequential
+ return ModelResponse(
+ parts=[
+ ToolCallPart("increment", {}, tool_call_id="one"),
+ ToolCallPart("increment", {}, tool_call_id="two"),
+ ]
+ )
+ assert [p.content for p in parts] == [1, 2]
+ return ModelResponse(parts=[TextPart("done")])
+
+ async with httpx.AsyncClient() as client:
+ deps = load_modules(request(RunLayerSpec(name="counter")), Services(client, client), "test", registry=registry)
+ native = create_modules(deps, registry=registry)["counter"]
+ await Agent(FunctionModel(model), deps_type=Deps, toolsets=[native]).run("increment twice", deps=deps)
+ assert snapshot_modules(deps, registry=registry).layers["counter"] == {"count": 2}
diff --git a/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py b/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py
index 71af4d7a3f0..fb43ce70103 100644
--- a/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py
+++ b/dify-agent/tests/local/dify_agent/runtime/test_run_scheduler.py
@@ -1,3 +1,4 @@
+from dify_agent.runtime.context import Services
import asyncio
from collections import defaultdict
from collections.abc import Mapping
@@ -6,12 +7,11 @@ from typing import cast
import httpx
import pytest
-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot
-from agenton.layers import LifecycleState
-from agenton_collections.layers.plain import PromptLayerConfig
+from dify_agent.protocol.snapshot import SessionSnapshot
+from dify_agent.layers.prompt import Config as PromptConfig
from dify_agent.layers.dify_plugin import DifyPluginLLMLayerConfig
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
+from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
+from dify_agent.layers.output import DifyOutputLayerConfig
from dify_agent.protocol import DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID, RunFailureType
from dify_agent.protocol.schemas import (
AgentRunUsage,
@@ -47,36 +47,24 @@ def _request(
output_config: Mapping[str, object] | DifyOutputLayerConfig | None = None,
) -> CreateRunRequest:
layers = [
- RunLayerSpec(name="prompt", type="plain.prompt", config=PromptLayerConfig(user=user)),
+ RunLayerSpec(name="prompt", config=(PromptConfig(user=user)).model_dump(mode="json")),
RunLayerSpec(
name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
+ config=(
+ DifyExecutionContextLayerConfig(
+ tenant_id="tenant-1", user_from="account", agent_mode="workflow_run", invoke_from="service-api"
+ )
+ ).model_dump(mode="json"),
),
RunLayerSpec(
name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
+ config=(
+ DifyPluginLLMLayerConfig(plugin_id="langgenius/openai", model_provider="openai", model="demo-model")
+ ).model_dump(mode="json"),
),
]
if output_config is not None:
- layers.append(
- RunLayerSpec(
- name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=output_config,
- )
- )
+ layers.append(RunLayerSpec(name=DIFY_AGENT_OUTPUT_LAYER_ID, config=output_config))
return CreateRunRequest(composition=RunComposition(layers=layers))
@@ -176,7 +164,7 @@ class FakeStore:
run_id: str,
intent: RunCancellationIntent,
*,
- session_snapshot: CompositorSessionSnapshot | None = None,
+ session_snapshot: SessionSnapshot | None = None,
usage: AgentRunUsage | None = None,
) -> RunFinalizationResult:
current_status = self.statuses[run_id]
@@ -269,7 +257,7 @@ class CancellationDuringShutdownFailureStore(FakeStore):
class SnapshotlessRunner:
@property
- def terminal_session_snapshot(self) -> CompositorSessionSnapshot | None:
+ def terminal_session_snapshot(self) -> SessionSnapshot | None:
return None
@property
@@ -281,7 +269,7 @@ class ControlledRunner:
started: asyncio.Event
release: asyncio.Event
finished: asyncio.Event | None
- _terminal_session_snapshot: CompositorSessionSnapshot
+ _terminal_session_snapshot: SessionSnapshot
_terminal_usage: AgentRunUsage | None
def __init__(
@@ -295,11 +283,11 @@ class ControlledRunner:
self.started = started
self.release = release
self.finished = finished
- self._terminal_session_snapshot = CompositorSessionSnapshot(layers=[])
+ self._terminal_session_snapshot = SessionSnapshot(layers={})
self._terminal_usage = usage
@property
- def terminal_session_snapshot(self) -> CompositorSessionSnapshot:
+ def terminal_session_snapshot(self) -> SessionSnapshot:
return self._terminal_session_snapshot
@property
@@ -343,7 +331,7 @@ class SuccessThenWaitRunner(SnapshotlessRunner):
self.store,
run_id=self.run_id,
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
)
assert result.applied is True
self.finalized.set()
@@ -378,7 +366,7 @@ class IgnoreCancellationThenSucceedRunner(SnapshotlessRunner):
self.store,
run_id=self.run_id,
output="late success",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
)
assert result.applied is False
assert result.status == "running"
@@ -410,7 +398,7 @@ class ReleaseThenSucceedRunner(SnapshotlessRunner):
self.store,
run_id=self.run_id,
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
)
assert result.applied is True
finally:
@@ -458,7 +446,7 @@ class FinalizeSuccessOnCancellationRunner(SnapshotlessRunner):
self.store,
run_id=self.run_id,
output="completed during shutdown",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
)
assert result.applied is True
@@ -470,12 +458,11 @@ def test_default_runner_factory_passes_runtime_limits_to_runner() -> None:
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
run_timeout_seconds=17,
stream_text_delta_coalescing_enabled=False,
stream_text_delta_flush_interval_seconds=0.25,
stream_text_delta_max_chars=2048,
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
runner = scheduler._default_runner_factory(record, _request(), is_cancelled=lambda: False)
@@ -497,16 +484,13 @@ def test_default_runner_factory_passes_agent_observability_instance() -> None:
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
agent_observability=sentinel,
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
runner = scheduler._default_runner_factory(record, _request(), is_cancelled=lambda: False)
default_scheduler = RunScheduler(
- store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
)
default_runner = default_scheduler._default_runner_factory(record, _request(), is_cancelled=lambda: False)
@@ -526,9 +510,8 @@ def test_create_run_starts_background_task_and_returns_running() -> None:
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda _record, _request: ControlledRunner(started=started, release=release),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
@@ -551,10 +534,9 @@ def test_shutdown_marks_unfinished_runs_failed_and_appends_event() -> None:
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
shutdown_grace_seconds=0,
runner_factory=lambda _record, _request: ControlledRunner(started=started, release=asyncio.Event()),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
await asyncio.wait_for(started.wait(), timeout=1)
@@ -577,13 +559,9 @@ def test_shutdown_failure_finalization_yields_to_concurrent_cancellation_intent(
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
shutdown_grace_seconds=0,
- runner_factory=lambda _record, _request: ControlledRunner(
- started=started,
- release=asyncio.Event(),
- ),
+ runner_factory=lambda _record, _request: ControlledRunner(started=started, release=asyncio.Event()),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
await asyncio.wait_for(started.wait(), timeout=1)
@@ -596,7 +574,7 @@ def test_shutdown_failure_finalization_yields_to_concurrent_cancellation_intent(
terminal = store.events[record.run_id][0]
assert isinstance(terminal, RunCancelledEvent)
assert terminal.data.reason == "concurrent_shutdown_cancel"
- assert terminal.data.session_snapshot == CompositorSessionSnapshot(layers=[])
+ assert terminal.data.session_snapshot == SessionSnapshot(layers={})
asyncio.run(scenario())
@@ -610,13 +588,10 @@ def test_cancellation_observer_failure_stops_runner_and_finalizes_failed() -> No
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda _record, _request: ControlledRunner(
- started=runner_started,
- release=asyncio.Event(),
- finished=runner_finished,
+ started=runner_started, release=asyncio.Event(), finished=runner_finished
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
supervisor_task = scheduler.active_tasks[record.run_id]
@@ -645,13 +620,10 @@ def test_cancellation_observer_failure_finalizes_concurrent_intent_after_runner_
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda _record, _request: ControlledRunner(
- started=runner_started,
- release=asyncio.Event(),
- finished=runner_finished,
+ started=runner_started, release=asyncio.Event(), finished=runner_finished
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
supervisor_task = scheduler.active_tasks[record.run_id]
@@ -671,7 +643,7 @@ def test_cancellation_observer_failure_finalizes_concurrent_intent_after_runner_
assert [event.type for event in store.events[record.run_id]] == ["run_cancelled"]
terminal = store.events[record.run_id][0]
assert isinstance(terminal, RunCancelledEvent)
- assert terminal.data.session_snapshot == CompositorSessionSnapshot(layers=[])
+ assert terminal.data.session_snapshot == SessionSnapshot(layers={})
asyncio.run(scenario())
@@ -684,19 +656,16 @@ def test_non_owner_cancel_run_stops_owner_task_and_persists_cancelled_terminal()
async with httpx.AsyncClient() as client:
owner_scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda _record, _request: ControlledRunner(
started=started,
release=asyncio.Event(),
finished=runner_finished,
usage=AgentRunUsage(prompt_tokens=13, completion_tokens=8),
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
remote_scheduler = RunScheduler(
- store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
)
record = await owner_scheduler.create_run(_request())
owner_task = owner_scheduler.active_tasks[record.run_id]
@@ -716,7 +685,7 @@ def test_non_owner_cancel_run_stops_owner_task_and_persists_cancelled_terminal()
assert [event.type for event in store.events[record.run_id]] == ["run_cancelled"]
terminal = store.events[record.run_id][0]
assert isinstance(terminal, RunCancelledEvent)
- assert terminal.data.session_snapshot == CompositorSessionSnapshot(layers=[])
+ assert terminal.data.session_snapshot == SessionSnapshot(layers={})
assert terminal.data.usage is not None
assert terminal.data.usage.prompt_tokens == 13
assert terminal.data.usage.completion_tokens == 8
@@ -738,21 +707,12 @@ def test_pre_enter_cancellation_does_not_copy_input_session_snapshot() -> None:
store = FakeStore()
started = asyncio.Event()
request = _request()
- request.session_snapshot = CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(
- name="prior",
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={"value": "prior"},
- )
- ]
- )
+ request.session_snapshot = SessionSnapshot(layers={"prior": {"value": "prior"}})
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda _record, _request: PreEnterBlockingRunner(started=started),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(request)
supervisor = scheduler.active_tasks[record.run_id]
@@ -777,14 +737,10 @@ def test_cancel_run_does_not_override_successful_terminal() -> None:
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda record, _request: SuccessThenWaitRunner(
- store=store,
- run_id=record.run_id,
- finalized=finalized,
- release=release,
+ store=store, run_id=record.run_id, finalized=finalized, release=release
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
await asyncio.wait_for(finalized.wait(), timeout=1)
@@ -811,16 +767,11 @@ def test_cancelled_terminal_survives_shutdown_while_runner_cleanup_is_pending()
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
shutdown_grace_seconds=0,
runner_factory=lambda record, _request: IgnoreCancellationThenSucceedRunner(
- store=store,
- run_id=record.run_id,
- started=started,
- release=release,
- finished=runner_finished,
+ store=store, run_id=record.run_id, started=started, release=release, finished=runner_finished
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
supervisor_task = scheduler.active_tasks[record.run_id]
@@ -870,8 +821,6 @@ def test_failure_and_cancellation_keep_the_first_terminal(
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
runner_factory=lambda record, _request: CompetingFailureRunner(
store=store,
run_id=record.run_id,
@@ -879,6 +828,7 @@ def test_failure_and_cancellation_keep_the_first_terminal(
release=release_runner,
failure_attempted=failure_attempted,
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
supervisor_task = scheduler.active_tasks[record.run_id]
@@ -916,8 +866,6 @@ def test_shutdown_grace_allows_runner_first_completion_and_reaps_children() -> N
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
shutdown_grace_seconds=1,
runner_factory=lambda record, _request: ReleaseThenSucceedRunner(
store=store,
@@ -926,6 +874,7 @@ def test_shutdown_grace_allows_runner_first_completion_and_reaps_children() -> N
release=release_runner,
finished=runner_finished,
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
supervisor_task = scheduler.active_tasks[record.run_id]
@@ -955,14 +904,11 @@ def test_shutdown_does_not_append_failed_after_success_wins() -> None:
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
shutdown_grace_seconds=0,
runner_factory=lambda record, _request: FinalizeSuccessOnCancellationRunner(
- store=store,
- run_id=record.run_id,
- started=started,
+ store=store, run_id=record.run_id, started=started
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
record = await scheduler.create_run(_request())
await asyncio.wait_for(started.wait(), timeout=1)
@@ -979,7 +925,9 @@ def test_cancel_run_rejects_finished_run() -> None:
async def scenario() -> None:
store = FakeStore()
async with httpx.AsyncClient() as client:
- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)
+ scheduler = RunScheduler(
+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
+ )
record = await store.create_run()
store.statuses[record.run_id] = "succeeded"
@@ -993,7 +941,9 @@ def test_create_run_accepts_blank_prompt_and_runner_fails_asynchronously() -> No
async def scenario() -> None:
store = FakeStore()
async with httpx.AsyncClient() as client:
- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)
+ scheduler = RunScheduler(
+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
+ )
record = await scheduler.create_run(_request(["", " "]))
await asyncio.wait_for(scheduler.active_tasks[record.run_id], timeout=1)
@@ -1010,7 +960,9 @@ def test_create_run_accepts_invalid_output_schema_and_runner_fails_asynchronousl
async def scenario() -> None:
store = FakeStore()
async with httpx.AsyncClient() as client:
- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)
+ scheduler = RunScheduler(
+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
+ )
record = await scheduler.create_run(
_request(
@@ -1029,69 +981,12 @@ def test_create_run_accepts_invalid_output_schema_and_runner_fails_asynchronousl
asyncio.run(scenario())
-def test_create_run_honors_explicit_empty_layer_providers_by_failing_after_persisting() -> None:
+def test_create_run_rejects_after_shutdown_starts() -> None:
async def scenario() -> None:
- store = FakeStore()
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
- store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=(),
- )
-
- record = await scheduler.create_run(_request())
- await asyncio.wait_for(scheduler.active_tasks[record.run_id], timeout=1)
-
- assert store.records == {record.run_id: record}
- assert [event.type for event in store.events[record.run_id]] == ["run_started", "run_failed"]
- assert store.statuses[record.run_id] == "failed"
- assert "plain.prompt" in (store.errors[record.run_id] or "")
-
- asyncio.run(scenario())
-
-
-def test_create_run_accepts_closed_session_snapshot_and_runner_fails_asynchronously() -> None:
- async def scenario() -> None:
- store = FakeStore()
- async with httpx.AsyncClient() as client:
- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)
- request = _request()
- request.session_snapshot = CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(
- name="prompt",
- lifecycle_state=LifecycleState.CLOSED,
- runtime_state={},
- ),
- LayerSessionSnapshot(
- name="execution_context",
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={},
- ),
- LayerSessionSnapshot(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={},
- ),
- ]
+ store=FakeStore(), services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
)
-
- record = await scheduler.create_run(request)
- await asyncio.wait_for(scheduler.active_tasks[record.run_id], timeout=1)
-
- assert store.records == {record.run_id: record}
- assert [event.type for event in store.events[record.run_id]] == ["run_started", "run_failed"]
- assert store.statuses[record.run_id] == "failed"
- assert "CLOSED snapshots cannot be entered" in (store.errors[record.run_id] or "")
-
- asyncio.run(scenario())
-
-
-def test_create_run_rejects_after_shutdown_starts() -> None:
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- scheduler = RunScheduler(store=FakeStore(), plugin_daemon_http_client=client, dify_api_http_client=client)
await scheduler.shutdown()
with pytest.raises(SchedulerStoppingError):
@@ -1104,7 +999,9 @@ def test_create_run_rejects_invalid_request_after_shutdown_without_persisting()
async def scenario() -> None:
store = FakeStore()
async with httpx.AsyncClient() as client:
- scheduler = RunScheduler(store=store, plugin_daemon_http_client=client, dify_api_http_client=client)
+ scheduler = RunScheduler(
+ store=store, services=Services(plugin_daemon_http_client=client, dify_api_http_client=client)
+ )
await scheduler.shutdown()
with pytest.raises(SchedulerStoppingError):
@@ -1124,12 +1021,11 @@ def test_shutdown_waits_for_in_flight_create_to_register_before_cancelling() ->
async with httpx.AsyncClient() as client:
scheduler = RunScheduler(
store=store,
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
shutdown_grace_seconds=0,
runner_factory=lambda _record, _request: ControlledRunner(
started=runner_started, release=asyncio.Event()
),
+ services=Services(plugin_daemon_http_client=client, dify_api_http_client=client),
)
create_task = asyncio.create_task(scheduler.create_run(_request()))
diff --git a/dify-agent/tests/local/dify_agent/runtime/test_runner.py b/dify-agent/tests/local/dify_agent/runtime/test_runner.py
index be963726254..ba869daabe5 100644
--- a/dify-agent/tests/local/dify_agent/runtime/test_runner.py
+++ b/dify-agent/tests/local/dify_agent/runtime/test_runner.py
@@ -1,3478 +1,501 @@
+"""Run the real native Agent to verify history, output and cleanup boundaries."""
+
import asyncio
-from collections.abc import AsyncIterator, Generator, Iterable, Mapping
-from contextlib import contextmanager
-from decimal import Decimal
-from typing import Any, ClassVar, cast
+from dataclasses import replace
+from types import SimpleNamespace
import httpx
import pytest
-from graphon.model_runtime.entities.llm_entities import LLMUsage
-from pydantic import JsonValue
-from pydantic_ai import Tool
-from pydantic_ai.exceptions import ModelHTTPError, UnexpectedModelBehavior, UsageLimitExceeded
+from pydantic_ai import Agent, Tool
+from pydantic_ai.exceptions import ModelHTTPError, UsageLimitExceeded
from pydantic_ai.messages import (
- ToolReturnPart,
- ModelMessage,
+ UserPromptPart,
ModelRequest,
ModelResponse,
- SystemPromptPart,
- TextPart,
+ RetryPromptPart,
ToolCallPart,
- UserPromptPart,
-)
-from pydantic_ai.models import ModelRequestParameters
-from pydantic_ai.models.function import DeltaToolCall, DeltaToolCalls, FunctionModel
-from pydantic_ai.models.test import TestModel
-from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults
-from pydantic_ai.usage import UsageLimits
-from pydantic_ai.settings import ModelSettings
-from pydantic_ai_harness.compaction import TieredCompaction
-
-from agenton.compositor import CompositorSessionSnapshot, LayerProvider, LayerSessionSnapshot
-from agenton.layers import ExitIntent, LifecycleState
-from agenton_collections.layers.pydantic_ai import PYDANTIC_AI_HISTORY_LAYER_TYPE_ID, PydanticAIHistoryRuntimeState
-from agenton_collections.layers.plain import PromptLayerConfig, ToolsLayer
-from dify_agent.layers.ask_human import DIFY_ASK_HUMAN_LAYER_TYPE_ID, DifyAskHumanLayerConfig
-from dify_agent.layers.execution_context import DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID, DifyExecutionContextLayerConfig
-from dify_agent.layers.runtime import DIFY_RUNTIME_LAYER_TYPE_ID, DifyRuntimeLayerConfig
-from dify_agent.layers.shell import DIFY_SHELL_LAYER_TYPE_ID, DifyShellLayerConfig
-from dify_agent.layers.dify_plugin.configs import (
- DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- DifyPluginLLMLayerConfig,
- DifyPluginToolConfig,
- DifyPluginToolParameter,
- DifyPluginToolParameterForm,
- DifyPluginToolParameterType,
- DifyPluginToolsLayerConfig,
-)
-from dify_agent.layers.dify_plugin.llm_layer import DifyPluginLLMLayer
-from dify_agent.layers.dify_plugin.tools_layer import DifyPluginToolsLayer
-from dify_agent.layers.dify_core_tools.configs import (
- DIFY_CORE_TOOLS_LAYER_TYPE_ID,
- DifyCoreToolConfig,
- DifyCoreToolsLayerConfig,
+ ToolReturnPart,
)
-from dify_agent.layers.dify_core_tools.layer import DifyCoreToolsLayer
-from dify_agent.layers.knowledge.client import DifyKnowledgeBaseClientError
-from dify_agent.layers.knowledge.configs import DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID, DifyKnowledgeBaseLayerConfig
-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer
-from dify_agent.layers.output import DIFY_OUTPUT_LAYER_TYPE_ID, DifyOutputLayerConfig
-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID, DIFY_AGENT_MODEL_LAYER_ID, DIFY_AGENT_OUTPUT_LAYER_ID
+from pydantic_ai.models.function import DeltaToolCall, FunctionModel
+from pydantic_ai.tools import DeferredToolRequests
+
+from dify_agent.adapters.shell.protocols import ShellCommandResult
+from dify_agent.layers import history
+from dify_agent.layers.dify_plugin import llm_layer
from dify_agent.protocol.schemas import (
CreateRunRequest,
- DeferredToolResultsPayload,
- LayerExitSignals,
- PydanticAIStreamRunEvent,
RunComposition,
RunFailedEvent,
- RunFailureType,
RunLayerSpec,
RunSucceededEvent,
+ RunFailureType,
)
-
-from dify_agent.runtime.observability import AgentObservability
+from dify_agent.protocol.snapshot import SessionSnapshot
+from dify_agent.runtime.context import Services
from dify_agent.runtime.event_sink import InMemoryRunEventSink
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
-from dify_agent.runtime.runner import (
- AgentRunRunner,
- AgentRunValidationError,
- RunSuccessOutcome,
- _run_failed_error_payload,
-)
-from dify_agent.runtime_backend import (
- ExecutionBindingAllocation,
- ExecutionBindingCreateSpec,
- ExecutionBindingDestroySpec,
- HomeSnapshotBackend,
- RuntimeBackendProfile,
- RuntimeLayout,
- RuntimeLease,
-)
-from dify_agent.runtime_backend.shellctl import ShellctlRuntimeLease, create_shellctl_lease
-from shellctl.shared import DeleteJobResponse, JobResult, JobStatusName, JobStatusView
-
-
-class StaticToolsTestLayer(ToolsLayer):
- type_id: ClassVar[str | None] = "test.static.tools"
-
-
-class FakeRunnerShellctlClient:
- run_calls: list[tuple[str, str | None, Mapping[str, str] | None, float]]
- delete_calls: list[tuple[str, bool, float | None]]
- closed: bool
-
- def __init__(self) -> None:
- self.run_calls = []
- self.delete_calls = []
- self.closed = False
-
- async def run(
- self,
- script: str,
- *,
- cwd: str | None = None,
- env: Mapping[str, str] | None = None,
- timeout: float = 10.0,
- ) -> JobResult:
- self.run_calls.append((script, cwd, env, timeout))
- return JobResult(
- job_id="mkdir-job",
- status=JobStatusName.EXITED,
- done=True,
- exit_code=0,
- output_path="/tmp/output.log",
- output="",
- offset=0,
- truncated=False,
- )
-
- async def close(self) -> None:
- self.closed = True
-
- async def wait(self, job_id: str, *, offset: int, timeout: float = 10.0) -> JobResult:
- del job_id, offset, timeout
- raise AssertionError("wait() should not be called in this test")
-
- async def input(self, job_id: str, text: str, *, offset: int, timeout: float = 10.0) -> JobResult:
- del job_id, text, offset, timeout
- raise AssertionError("input() should not be called in this test")
-
- async def terminate(self, job_id: str, grace_seconds: float = 2.0) -> JobStatusView:
- del job_id, grace_seconds
- raise AssertionError("terminate() should not be called in this test")
-
- async def delete(
- self,
- job_id: str,
- *,
- force: bool = False,
- grace_seconds: float | None = None,
- ) -> DeleteJobResponse:
- self.delete_calls.append((job_id, force, grace_seconds))
- return DeleteJobResponse(job_id=job_id)
-
-
-class FakeRunnerExecutionBindingBackend:
- def __init__(self, client: FakeRunnerShellctlClient) -> None:
- self.client = client
-
- async def create_binding(self, spec: ExecutionBindingCreateSpec) -> ExecutionBindingAllocation:
- return ExecutionBindingAllocation(binding_ref=spec.binding_id, workspace_ref=spec.workspace_id)
-
- async def acquire(self, binding_ref: str) -> RuntimeLease:
- return create_shellctl_lease(
- handle=binding_ref,
- layout=RuntimeLayout(
- home_dir="/home/agent-1",
- workspace_dir="/home/agent-1/workspace/abc12ff",
- ),
- entrypoint="http://shellctl",
- token="",
- client_factory=lambda: self.client, # pyright: ignore[reportArgumentType]
- )
-
- async def release(self, lease: RuntimeLease) -> None:
- assert isinstance(lease, ShellctlRuntimeLease)
- await lease.close()
-
- async def destroy_binding(self, spec: ExecutionBindingDestroySpec) -> None:
- del spec
-
-
-def test_run_failed_error_payload_preserves_plugin_rate_limit_error() -> None:
- exc = ModelHTTPError(
- 429,
- "gpt-4o-mini",
- {"error_type": "InvokeRateLimitError", "message": "quota exceeded"},
- )
-
- message, error_type, reason = _run_failed_error_payload(exc)
-
- assert message == "quota exceeded"
- assert error_type is None
- assert reason == "InvokeRateLimitError"
-
-
-def test_run_failed_error_payload_infers_rate_limit_reason_from_status_code() -> None:
- exc = ModelHTTPError(429, "gpt-4o-mini", {"message": "too many requests"})
-
- message, error_type, reason = _run_failed_error_payload(exc)
-
- assert message == "too many requests"
- assert error_type is None
- assert reason == "InvokeRateLimitError"
-
-
-def test_run_failed_error_payload_preserves_knowledge_error_code() -> None:
- exc = DifyKnowledgeBaseClientError(
- "Knowledge base search failed with HTTP 400 (dataset_not_found): Dataset not found",
- status_code=400,
- error_code="dataset_not_found",
- retryable=False,
- )
-
- message, error_type, reason = _run_failed_error_payload(exc)
+from dify_agent.runtime.runner import AgentRunRunner
+from dify_agent.runtime_backend import RuntimeBackendProfile, RuntimeLayout
- assert message == "Knowledge base search failed with HTTP 400 (dataset_not_found): Dataset not found"
- assert error_type is None
- assert reason == "dataset_not_found"
-
-def test_run_failed_error_payload_classifies_usage_limit() -> None:
- exc = UsageLimitExceeded("The next request would exceed the request_limit of 500")
-
- message, error_type, reason = _run_failed_error_payload(exc)
-
- assert message.startswith("The next request would exceed the request_limit of 500")
- assert error_type is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED
- assert reason is None
-
-
-def test_cancelled_runner_does_not_emit_late_failure(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- async def scenario() -> None:
- sink = InMemoryRunEventSink()
- cancelled = False
- async with httpx.AsyncClient() as client:
- runner = AgentRunRunner(
- sink=sink,
- request=_request(),
- run_id="run-cancelled",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- is_cancelled=lambda: cancelled,
- )
-
- async def fail_after_cancel() -> RunSuccessOutcome:
- nonlocal cancelled
- cancelled = True
- raise RuntimeError("late model failure")
-
- monkeypatch.setattr(runner, "_run_agent", fail_after_cancel)
- await runner.run()
-
- assert "run-cancelled" not in sink.statuses
- assert [event.type for event in sink.events["run-cancelled"]] == ["run_started"]
-
- asyncio.run(scenario())
-
-
-def _request(
- user: str | list[str] = "hello",
- *,
- include_history: bool = False,
- include_ask_human: bool = False,
- ask_human_config: DifyAskHumanLayerConfig | None = None,
- llm_layer_name: str = DIFY_AGENT_MODEL_LAYER_ID,
- execution_context_layer_name: str = "execution_context",
- app_id: str | None = None,
- agent_id: str | None = None,
- on_exit: LayerExitSignals | None = None,
- output_config: Mapping[str, object] | DifyOutputLayerConfig | None = None,
- model_settings: ModelSettings | None = None,
- context_window_tokens: int | None = None,
-) -> CreateRunRequest:
- layers = [
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user=user),
- ),
- *(
- [RunLayerSpec(name=DIFY_AGENT_HISTORY_LAYER_ID, type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID)]
- if include_history
- else []
- ),
- *(
- [
+def request(*extra, snapshot=None, instruction="Current instruction", user="hello"):
+ return CreateRunRequest(
+ composition=RunComposition(
+ layers=[
RunLayerSpec(
- name="ask_human",
- type=DIFY_ASK_HUMAN_LAYER_TYPE_ID,
- config=ask_human_config or DifyAskHumanLayerConfig(),
- )
+ name="execution_context",
+ config={
+ "tenant_id": "tenant",
+ "user_id": "user",
+ "user_from": "account",
+ "app_id": "app",
+ "agent_mode": "agent_app",
+ "invoke_from": "web-app",
+ },
+ ),
+ RunLayerSpec(name="llm", config={"plugin_id": "openai", "model_provider": "openai", "model": "demo"}),
+ RunLayerSpec(name="prompt", config={"prefix": instruction, "user": user}),
+ RunLayerSpec(name="history"),
+ *extra,
]
- if include_ask_human
- else []
- ),
- RunLayerSpec(
- name=execution_context_layer_name,
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- app_id=app_id,
- agent_id=agent_id,
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=llm_layer_name,
- type="dify.plugin.llm",
- deps={"execution_context": execution_context_layer_name},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- model_settings=model_settings,
- context_window_tokens=context_window_tokens,
- ),
),
- ]
- if output_config is not None:
- layers.append(
- RunLayerSpec(
- name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=output_config,
- )
+ session_snapshot=snapshot,
+ )
+
+
+def run_runner(incoming, services, monkeypatch, stream, *, run_id="test", timeout=10):
+ model = FunctionModel(stream_function=stream)
+ monkeypatch.setattr(llm_layer.Capability, "build_model", lambda self, deps: model)
+ sink = InMemoryRunEventSink()
+ runner = AgentRunRunner(sink=sink, request=incoming, run_id=run_id, services=services, run_timeout_seconds=timeout)
+ return runner, sink
+
+
+async def test_native_run_restores_conversation_but_uses_current_instructions(monkeypatch):
+ seen = []
+
+ async def stream(messages, info):
+ seen.append((list(messages), info.instructions))
+ yield "reply"
+
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client)
+ first, first_sink = run_runner(request(), services, monkeypatch, stream, run_id="first")
+ await first.run()
+ terminal = first_sink.events["first"][-1]
+ assert isinstance(terminal, RunSucceededEvent)
+ assert terminal.data.output == "reply"
+ snapshot = terminal.data.session_snapshot
+ state = history.State.model_validate(snapshot.layers["history"])
+ assert len(state.messages) == 2
+ assert all(m.instructions is None for m in state.messages if isinstance(m, ModelRequest))
+ second, sink = run_runner(
+ request(snapshot=snapshot, instruction="Revised instruction", user="next"),
+ services,
+ monkeypatch,
+ stream,
+ run_id="second",
)
-
- return CreateRunRequest(
- composition=RunComposition(layers=layers),
- on_exit=on_exit or LayerExitSignals(),
+ await second.run()
+ assert len(seen[1][0]) == 3
+ assert seen[1][1] == "Revised instruction"
+ assert "Current instruction" not in snapshot.model_dump_json()
+ assert isinstance(sink.events["second"][-1], RunSucceededEvent)
+ assert not client.is_closed
+
+
[email protected]("with_regular_tool", [False, True])
+async def test_legacy_ask_human_pause_accepts_first_new_user_turn(monkeypatch, with_regular_tool):
+ """Produce real deferred history, migrate only data, then use the new runner."""
+
+ async def ask_human(question: str) -> str:
+ pytest.fail("the legacy external tool must never execute")
+
+ async def regular() -> str:
+ return "completed regular tool"
+
+ def legacy_model(messages, info):
+ calls = [ToolCallPart(tool_name="ask_human", args={"question": "Choose an action"}, tool_call_id="human-1")]
+ if with_regular_tool:
+ calls.append(ToolCallPart(tool_name="regular", args={}, tool_call_id="regular-1"))
+ return ModelResponse(parts=calls)
+
+ legacy_agent = Agent(
+ FunctionModel(legacy_model),
+ tools=[Tool(ask_human, prepare=lambda ctx, definition: replace(definition, kind="external")), regular],
+ output_type=[str, DeferredToolRequests],
+ )
+ paused = await legacy_agent.run("Original request")
+ assert isinstance(paused.output, DeferredToolRequests)
+ legacy_state = history.State(messages=paused.all_messages()).model_dump(mode="json")
+ assert legacy_state["messages"][-1]["state"] == "complete"
+ snapshot = SessionSnapshot.model_validate(
+ {
+ "schema_version": 1,
+ "layers": [
+ {"name": "history", "lifecycle_state": "suspended", "runtime_state": legacy_state},
+ {"name": "ask_human", "lifecycle_state": "suspended", "runtime_state": {}},
+ ],
+ }
)
-
-
-def _request_with_shell() -> CreateRunRequest:
- request = _request()
- request.composition.layers[-1:-1] = [
- RunLayerSpec(
- name="runtime",
- type=DIFY_RUNTIME_LAYER_TYPE_ID,
- config=DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),
- ),
- RunLayerSpec(
- name="shell",
- type=DIFY_SHELL_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context", "runtime": "runtime"},
- config=DifyShellLayerConfig(),
- ),
- ]
- return request
-
-
-def _recursive_output_schema() -> dict[str, object]:
- return {
- "type": "object",
- "properties": {"node": {"$ref": "#/$defs/node"}},
- "$defs": {
- "node": {
+ assert "ask_human" not in snapshot.layers
+ assert snapshot.layers["history"]["messages"][:-1] == legacy_state["messages"][:-1]
+ assert snapshot.layers["history"]["messages"][-1] == {
+ **legacy_state["messages"][-1],
+ "state": "interrupted",
+ }
+ # Loading a snapshot must not mutate the stored legacy object.
+ assert legacy_state["messages"][-1]["state"] == "complete"
+ model_calls = []
+
+ async def stream(messages, info):
+ model_calls.append(messages)
+ assert any(
+ isinstance(part, UserPromptPart) and part.content == "Original request"
+ for message in messages
+ for part in message.parts
+ )
+ returns = {
+ part.tool_call_id: part.content
+ for message in messages
+ if isinstance(message, ModelRequest)
+ for part in message.parts
+ if isinstance(part, ToolReturnPart)
+ }
+ assert "human-1" in returns
+ if with_regular_tool:
+ assert returns["regular-1"] == "completed regular tool"
+ assert messages[-1].parts[-1].content == "Continue without waiting for human input"
+ yield "continued"
+
+ async with httpx.AsyncClient() as client:
+ runner, sink = run_runner(
+ request(snapshot=snapshot, user="Continue without waiting for human input"),
+ Services(client, client),
+ monkeypatch,
+ stream,
+ )
+ await runner.run()
+ assert len(model_calls) == 1
+ terminal = sink.events["test"][-1]
+ assert isinstance(terminal, RunSucceededEvent)
+ assert terminal.data.output == "continued"
+
+
+async def test_failure_saves_user_history_and_classified_event(monkeypatch):
+ async def stream(messages, info):
+ raise ModelHTTPError(429, "demo", {"error_type": "InvokeRateLimitError", "message": "quota exceeded"})
+ yield "unreachable"
+
+ async with httpx.AsyncClient() as client:
+ runner, sink = run_runner(request(), Services(client, client), monkeypatch, stream)
+ with pytest.raises(ModelHTTPError):
+ await runner.run()
+ terminal = sink.events["test"][-1]
+ assert isinstance(terminal, RunFailedEvent)
+ assert terminal.data.error == "quota exceeded"
+ assert terminal.data.reason == "InvokeRateLimitError"
+ assert terminal.data.session_snapshot is not None
+ saved = history.State.model_validate(terminal.data.session_snapshot.layers["history"])
+ assert isinstance(saved.messages[0], ModelRequest)
+ assert saved.messages[0].instructions is None
+ assert saved.messages[-1].state == "interrupted"
+
+
[email protected]("invalid_first", [False, True])
+async def test_native_structured_output_uses_output_module(monkeypatch, invalid_first):
+ attempts = []
+
+ async def stream(messages, info):
+ assert len(info.output_tools) == 1
+ attempts.append(messages)
+ if invalid_first and len(attempts) == 1:
+ arguments = '{"answer":42}'
+ else:
+ if invalid_first:
+ assert any(isinstance(part, RetryPromptPart) for message in messages for part in message.parts)
+ arguments = '{"answer":"done"}'
+ yield {0: DeltaToolCall(name=info.output_tools[0].name, json_args=arguments, tool_call_id="out")}
+
+ spec = RunLayerSpec(
+ name="output",
+ config={
+ "json_schema": {
"type": "object",
- "properties": {"child": {"$ref": "#/$defs/node"}},
+ "properties": {"answer": {"type": "string"}},
+ "required": ["answer"],
"additionalProperties": False,
}
},
- "additionalProperties": False,
- }
-
-
-def _prepared_plugin_tool_parameters() -> list[DifyPluginToolParameter]:
- return [
- DifyPluginToolParameter(
- name="query",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.LLM,
- required=True,
- llm_description="Search query",
- ),
- DifyPluginToolParameter(
- name="auth_scope",
- type=DifyPluginToolParameterType.STRING,
- form=DifyPluginToolParameterForm.FORM,
- required=True,
- llm_description="Hidden auth scope",
- ),
- ]
-
-
-def _prepared_plugin_tool_schema() -> dict[str, JsonValue]:
- return {
- "type": "object",
- "properties": {
- "query": {"type": "string", "description": "Search query"},
- },
- "required": ["query"],
- }
-
+ )
+ async with httpx.AsyncClient() as client:
+ runner, sink = run_runner(request(spec), Services(client, client), monkeypatch, stream)
+ await runner.run()
+ terminal = sink.events["test"][-1]
+ assert isinstance(terminal, RunSucceededEvent)
+ assert terminal.data.output == {"answer": "done"}
+ assert len(attempts) == (2 if invalid_first else 1)
+
+
+class Commands:
+ """Remote command protocol double; the Agent and capability scopes stay real."""
+
+ def __init__(self):
+ self.deleted = []
+ self.scripts = []
+ self.tail_started = asyncio.Event()
+ self.block_tail = False
+ self.bootstrap_failures = 0
+
+ async def run(self, script, *, cwd=None, env=None, timeout=10, mode="pty"):
+ self.scripts.append(script)
+ if mode == "stdio":
+ failed = self.bootstrap_failures > 0
+ self.bootstrap_failures = max(0, self.bootstrap_failures - 1)
+ return ShellCommandResult("bootstrap", "exited", True, 1 if failed else 0, "", 0, False, "/tmp/output")
+ return ShellCommandResult("remote", "running", False, None, "partial", 20, self.block_tail, "/tmp/output")
+
+ async def tail(self, job_id, *, edge_bytes=None):
+ self.tail_started.set()
+ await asyncio.Event().wait()
-class SequenceOutputTestModel(TestModel):
- outputs: list[str | dict[str, Any] | None]
- request_count: int
-
- def __init__(self, outputs: list[str | dict[str, Any] | None]) -> None:
- super().__init__(call_tools=[])
- self.outputs = outputs
- self.request_count = 0
-
- def _request(
- self,
- messages: list[ModelMessage],
- model_settings: ModelSettings | None,
- model_request_parameters: ModelRequestParameters,
- ) -> ModelResponse:
- if not model_request_parameters.output_tools:
- return super()._request(messages, model_settings, model_request_parameters)
-
- output_tool = model_request_parameters.output_tools[0]
- next_index = min(self.request_count, len(self.outputs) - 1)
- output_args = self.outputs[next_index]
- self.request_count += 1
- return ModelResponse(
- parts=[
- ToolCallPart(
- output_tool.name,
- output_args,
- tool_call_id=f"pyd_ai_tool_call_id__{output_tool.name}_{self.request_count}",
- )
- ],
- model_name=self.model_name,
- )
+ async def delete(self, job_id, *, force=False, grace_seconds=None):
+ self.deleted.append(job_id)
-class RecordingTestModel(TestModel):
- seen_requests: list[list[ModelMessage]]
- seen_instructions: list[list[str]]
- failure: Exception | None
-
- def __init__(self, *, custom_output_text: str = "done", failure: Exception | None = None) -> None:
- super().__init__(call_tools=[], custom_output_text=custom_output_text)
- self.seen_requests = []
- self.seen_instructions = []
- self.failure = failure
-
- def _request(
- self,
- messages: list[ModelMessage],
- model_settings: ModelSettings | None,
- model_request_parameters: ModelRequestParameters,
- ) -> ModelResponse:
- self.seen_requests.append(list(messages))
- self.seen_instructions.append([part.content for part in model_request_parameters.instruction_parts or []])
- if self.failure is not None:
- raise self.failure
- return super()._request(messages, model_settings, model_request_parameters)
-
-
-def _history_session_snapshot(
- messages: list[ModelMessage],
- *,
- include_ask_human: bool = False,
- include_output: bool = False,
-) -> CompositorSessionSnapshot:
- layers = [
- LayerSessionSnapshot(name="prompt", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}),
- LayerSessionSnapshot(
- name=DIFY_AGENT_HISTORY_LAYER_ID,
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state=PydanticAIHistoryRuntimeState(messages=messages).model_dump(mode="json"),
- ),
- *(
- [LayerSessionSnapshot(name="ask_human", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={})]
- if include_ask_human
- else []
- ),
- LayerSessionSnapshot(name="execution_context", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}),
- LayerSessionSnapshot(
- name=DIFY_AGENT_MODEL_LAYER_ID, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}
- ),
- ]
- if include_output:
- layers.append(
- LayerSessionSnapshot(
- name=DIFY_AGENT_OUTPUT_LAYER_ID, lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}
- )
+class Backend:
+ def __init__(self, commands):
+ self.commands = commands
+ self.active = False
+ self.acquired = 0
+ self.released = 0
+ self.lease = SimpleNamespace(
+ handle="binding",
+ commands=commands,
+ layout=RuntimeLayout(home_dir="/home/agent", workspace_dir="/home/agent/workspace/run"),
)
- return CompositorSessionSnapshot(layers=layers)
-
-
-def _history_messages_from_snapshot(snapshot: CompositorSessionSnapshot) -> list[ModelMessage]:
- history_snapshot = next(layer for layer in snapshot.layers if layer.name == DIFY_AGENT_HISTORY_LAYER_ID)
- return PydanticAIHistoryRuntimeState.model_validate(history_snapshot.runtime_state).messages
-
-
-def _flatten_message_parts(messages: list[ModelMessage]) -> list[object]:
- return [part for message in messages for part in message.parts]
-
-def _assert_interrupted_history(
- snapshot: CompositorSessionSnapshot,
- stored_history: list[ModelMessage],
-) -> None:
- saved_history = _history_messages_from_snapshot(snapshot)
+ async def acquire(self, binding_ref):
+ assert binding_ref == "binding"
+ self.active = True
+ self.acquired += 1
+ return self.lease
- assert saved_history[: len(stored_history)] == stored_history
- assert len(saved_history) == len(stored_history) + 2
- current_request = saved_history[-2]
- assert isinstance(current_request, ModelRequest)
- assert current_request.instructions is None
- assert len(current_request.parts) == 1
- assert isinstance(current_request.parts[0], UserPromptPart)
- assert current_request.parts[0].content == "current user"
- partial_response = saved_history[-1]
- assert isinstance(partial_response, ModelResponse)
- assert partial_response.state == "interrupted"
- assert len(partial_response.parts) == 1
- assert isinstance(partial_response.parts[0], TextPart)
- assert partial_response.parts[0].content == "partial"
+ async def release(self, lease):
+ assert self.active
+ self.active = False
+ self.released += 1
-def _install_fake_message_capture(monkeypatch: pytest.MonkeyPatch) -> list[ModelMessage]:
- captured_messages: list[ModelMessage] = []
-
- @contextmanager
- def fake_capture_run_messages() -> Generator[list[ModelMessage]]:
- captured_messages.clear()
- yield captured_messages
-
- monkeypatch.setattr("dify_agent.runtime.runner.capture_run_messages", fake_capture_run_messages)
- return captured_messages
-
-
-class FakeAgentRunResult:
- output: object
-
- def __init__(self, output: object) -> None:
- self.output = output
-
-
-def test_runner_emits_terminal_success_and_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_clients: list[httpx.AsyncClient] = []
-
- def fake_get_model(self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert self.config.model == "demo-model"
- assert self.config.plugin_id == "langgenius/openai"
- seen_clients.append(http_client)
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request(execution_context_layer_name="renamed-execution-context")
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-1",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
- assert seen_clients == [client]
- assert client.is_closed is False
-
- asyncio.run(scenario())
-
- event_types = [event.type for event in sink.events["run-1"]]
- assert event_types[0] == "run_started"
- assert "pydantic_ai_event" in event_types
- assert "agent_output" not in event_types
- assert "session_snapshot" not in event_types
- assert event_types[-1:] == ["run_succeeded"]
- pydantic_events = [event for event in sink.events["run-1"] if isinstance(event, PydanticAIStreamRunEvent)]
- assert "".join(event.agent_message_delta or "" for event in pydantic_events) == "done"
- terminal = sink.events["run-1"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert terminal.data.output == "done"
- assert terminal.data.usage is not None
- assert terminal.data.usage.total_tokens > 0
- assert [layer.name for layer in terminal.data.session_snapshot.layers] == [
- "prompt",
- "renamed-execution-context",
- DIFY_AGENT_MODEL_LAYER_ID,
- ]
- assert [layer.lifecycle_state for layer in terminal.data.session_snapshot.layers] == [
- LifecycleState.SUSPENDED,
- LifecycleState.SUSPENDED,
- LifecycleState.SUSPENDED,
+def runtime_specs(*, bootstrap=False):
+ config = {"cli_tools": [{"name": "test", "install_commands": ["install-test"]}]} if bootstrap else {}
+ # Request ordering deliberately differs from resource ownership ordering.
+ return [
+ RunLayerSpec(name="shell", config=config),
+ RunLayerSpec(name="runtime", config={"backend_binding_ref": "binding"}),
]
- assert sink.statuses["run-1"] == "succeeded"
-
-
-def test_runner_emits_complete_plugin_usage_in_terminal_event(monkeypatch: pytest.MonkeyPatch) -> None:
- complete_usage = LLMUsage(
- prompt_tokens=10,
- prompt_unit_price=Decimal("5"),
- prompt_price_unit=Decimal("0.000001"),
- prompt_price=Decimal("0.000050"),
- completion_tokens=2,
- completion_unit_price=Decimal("30"),
- completion_price_unit=Decimal("0.000001"),
- completion_price=Decimal("0.000060"),
- total_tokens=12,
- total_price=Decimal("0.000110"),
- currency="USD",
- latency=0.4,
- time_to_first_token=0.1,
- time_to_generate=0.3,
- )
-
- class PricedTestModel(TestModel):
- @property
- def accumulated_usage(self) -> LLMUsage:
- return complete_usage
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return PricedTestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=_request(),
- run_id="run-priced",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-priced"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert terminal.data.usage is not None
- assert terminal.data.usage.prompt_unit_price == Decimal("5")
- assert terminal.data.usage.prompt_price == Decimal("0.000050")
- assert terminal.data.usage.completion_unit_price == Decimal("30")
- assert terminal.data.usage.completion_price == Decimal("0.000060")
- assert terminal.data.usage.total_price == Decimal("0.000110")
- assert terminal.data.usage.currency == "USD"
- assert terminal.data.usage.latency == 0.4
- assert terminal.data.usage.time_to_first_token == 0.1
- assert terminal.data.usage.time_to_generate == 0.3
-
-
-def test_runner_preserves_explicit_json_null_output(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- return FakeAgentRunResult(None)
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())
- request = _request()
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-null-output",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-null-output"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert terminal.data.output is None
- assert terminal.data.deferred_tool_call is None
- assert sink.statuses["run-null-output"] == "succeeded"
-
-
-def test_runner_passes_explicit_step_limit_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **kwargs: object) -> FakeAgentRunResult:
- usage_limits = cast(UsageLimits, kwargs["usage_limits"])
- assert usage_limits.request_limit == 500
- return FakeAgentRunResult("done")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=_request(),
- run_id="run-explicit-step-limit",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert sink.statuses["run-explicit-step-limit"] == "succeeded"
-
-
-def test_runner_passes_context_compaction(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **kwargs: object) -> FakeAgentRunResult:
- capabilities = cast(list[object], kwargs["capabilities"])
- assert len(capabilities) == 1
- capability = capabilities[0]
- assert isinstance(capability, TieredCompaction)
- assert capability.target_tokens == 7_000
- return FakeAgentRunResult("done")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=_request(
- model_settings={"max_tokens": 3_000},
- context_window_tokens=10_000,
- ),
- run_id="run-compaction",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert sink.statuses["run-compaction"] == "succeeded"
-
-
-def test_runner_instruments_agent_with_injected_observability(monkeypatch: pytest.MonkeyPatch) -> None:
- class FakeAgentObservability:
- def __init__(self) -> None:
- self.instrumented: list[tuple[object, DifyExecutionContextLayerConfig | None]] = []
-
- def instrument(
- self,
- agent: object,
- *,
- execution_context: DifyExecutionContextLayerConfig | None = None,
- ) -> None:
- self.instrumented.append((agent, execution_context))
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- return FakeAgentRunResult("done")
- observability = FakeAgentObservability()
- created_agent = FakeAgent()
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: created_agent)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=_request(app_id="app-1", agent_id="agent-1"),
- run_id="run-observed",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- agent_observability=cast(AgentObservability, observability),
- ).run()
-
- asyncio.run(scenario())
-
- assert sink.statuses["run-observed"] == "succeeded"
- # The run's Dify context reaches observability through the model layer's
- # execution-context dependency, whose node name the caller chooses.
- assert len(observability.instrumented) == 1
- instrumented_agent, execution_context = observability.instrumented[0]
- assert instrumented_agent is created_agent
- assert execution_context is not None
- assert (execution_context.tenant_id, execution_context.app_id, execution_context.agent_id) == (
- "tenant-1",
- "app-1",
- "agent-1",
- )
-
-
-def test_runner_rejects_compaction_budget_before_model_resolution_or_invocation(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- model_resolution_called = False
- agent_creation_called = False
- model_invocation_called = False
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- nonlocal model_resolution_called
- model_resolution_called = True
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- nonlocal model_invocation_called
- model_invocation_called = True
- return FakeAgentRunResult("unused")
-
- def fake_create_agent(*_args: object, **_kwargs: object) -> FakeAgent:
- nonlocal agent_creation_called
- agent_creation_called = True
- return FakeAgent()
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError,
- match="Model max_tokens must leave a positive input context budget",
- ):
- await AgentRunRunner(
- sink=sink,
- request=_request(
- model_settings={"max_tokens": 1_000},
- context_window_tokens=1_000,
- ),
- run_id="run-invalid-compaction-budget",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model_resolution_called is False
- assert agent_creation_called is False
- assert model_invocation_called is False
- assert [event.type for event in sink.events["run-invalid-compaction-budget"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-invalid-compaction-budget"] == "failed"
-
-
-def test_runner_timeout_excludes_tool_preparation_and_runtime_cleanup(monkeypatch: pytest.MonkeyPatch) -> None:
- shell_client = FakeRunnerShellctlClient()
- tools_prepared = False
-
- class SlowLifecycleBackend(FakeRunnerExecutionBindingBackend):
- acquired: bool = False
- released: bool = False
-
- async def acquire(self, binding_ref: str) -> RuntimeLease:
- await asyncio.sleep(0.01)
- lease = await super().acquire(binding_ref)
- self.acquired = True
- return lease
-
- async def release(self, lease: RuntimeLease) -> None:
- await asyncio.sleep(0.01)
- await super().release(lease)
- self.released = True
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- assert agent_run_id == "run-lifecycle-outside-timeout"
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class ImmediateAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- return FakeAgentRunResult("done")
-
- async def slow_resolve_run_tools(
- _run: object,
- *,
- plugin_daemon_http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- nonlocal tools_prepared
- assert plugin_daemon_http_client.is_closed is False
- assert dify_api_http_client.is_closed is False
- await asyncio.sleep(0.01)
- tools_prepared = True
- return []
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: ImmediateAgent())
- monkeypatch.setattr("dify_agent.runtime.runner._resolve_run_tools", slow_resolve_run_tools)
- backend = SlowLifecycleBackend(shell_client)
- runtime_backend_profile = RuntimeBackendProfile(
- home_snapshots=cast(HomeSnapshotBackend, object()),
- execution_bindings=backend,
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=_request_with_shell(),
- run_id="run-lifecycle-outside-timeout",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=create_default_layer_providers(runtime_backend_profile=runtime_backend_profile),
- run_timeout_seconds=0.001,
- ).run()
-
- asyncio.run(scenario())
-
- assert sink.statuses["run-lifecycle-outside-timeout"] == "succeeded"
- assert tools_prepared is True
- assert backend.acquired is True
- assert backend.released is True
- assert shell_client.closed is True
-
-
-def test_runner_timeout_cancels_agent_and_releases_runtime_lease(monkeypatch: pytest.MonkeyPatch) -> None:
- agent_cancelled = False
- shell_client = FakeRunnerShellctlClient()
-
- class FakeUsageModel(TestModel):
- @property
- def accumulated_usage(self) -> LLMUsage:
- return LLMUsage.from_metadata(
- {
- "prompt_tokens": 13,
- "completion_tokens": 8,
- "total_tokens": 21,
- "total_price": "0.000210",
- "currency": "USD",
- }
- )
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- assert agent_run_id == "run-timeout"
- return FakeUsageModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> None:
- nonlocal agent_cancelled
- try:
- await asyncio.Event().wait()
- except asyncio.CancelledError:
- agent_cancelled = True
- raise
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())
- runtime_backend_profile = RuntimeBackendProfile(
- home_snapshots=cast(HomeSnapshotBackend, object()),
- execution_bindings=FakeRunnerExecutionBindingBackend(shell_client),
- )
- sink = InMemoryRunEventSink()
+async def test_cancellation_during_remote_observation_deletes_job_and_releases_lease(monkeypatch):
+ commands = Commands()
+ commands.block_tail = True
+ backend = Backend(commands)
+
+ async def stream(messages, info):
+ assert backend.active
+ assert {t.name for t in info.function_tools} == {"shell_run", "shell_wait", "shell_input", "shell_interrupt"}
+ assert all(t.sequential for t in info.function_tools)
+ yield {0: DeltaToolCall(name="shell_run", json_args='{"script":"sleep 100"}', tool_call_id="call")}
+
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))
+ runner, sink = run_runner(request(*runtime_specs()), services, monkeypatch, stream)
+ task = asyncio.create_task(runner.run())
+ await asyncio.wait_for(commands.tail_started.wait(), timeout=3)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert commands.deleted == ["remote"]
+ assert backend.released == 1 and not backend.active
+ snap = runner.terminal_session_snapshot
+ assert snap is not None
+ assert snap.layers["shell"] == {"initialized": True, "job_ids": [], "job_offsets": {}}
+ saved = history.State.model_validate(snap.layers["history"])
+ responses = [m for m in saved.messages if isinstance(m, ModelResponse)]
+ assert responses[-1].state == "interrupted"
+ assert not client.is_closed
+
+
+async def test_bootstrap_failure_retries_and_success_is_not_repeated(monkeypatch):
+ commands = Commands()
+ commands.bootstrap_failures = 1
+ backend = Backend(commands)
+
+ async def stream(messages, info):
+ assert backend.active
+ assert "Workspace" in info.instructions
+ yield "done"
+
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))
+ runner, sink = run_runner(request(*runtime_specs(bootstrap=True)), services, monkeypatch, stream)
+ with pytest.raises(RuntimeError, match="bootstrap"):
+ await runner.run()
+ assert runner.terminal_session_snapshot.layers["shell"]["initialized"] is False
+ second, _ = run_runner(
+ request(*runtime_specs(bootstrap=True), snapshot=runner.terminal_session_snapshot),
+ services,
+ monkeypatch,
+ stream,
+ run_id="second",
+ )
+ await second.run()
+ assert second.terminal_session_snapshot.layers["shell"]["initialized"] is True
+ third, _ = run_runner(
+ request(*runtime_specs(bootstrap=True), snapshot=second.terminal_session_snapshot),
+ services,
+ monkeypatch,
+ stream,
+ run_id="third",
+ )
+ await third.run()
+ assert len(commands.scripts) == 2
+ assert backend.acquired == backend.released == 3
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(UsageLimitExceeded, match="0.01 seconds"):
- await AgentRunRunner(
- sink=sink,
- request=_request_with_shell(),
- run_id="run-timeout",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=create_default_layer_providers(runtime_backend_profile=runtime_backend_profile),
- run_timeout_seconds=0.01,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-timeout"][-1]
- assert isinstance(terminal, RunFailedEvent)
- assert terminal.data.error_type is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED
- assert terminal.data.usage is not None
- assert terminal.data.usage.prompt_tokens == 13
- assert terminal.data.usage.completion_tokens == 8
- assert terminal.data.usage.total_tokens == 21
- assert terminal.data.usage.total_price == Decimal("0.000210")
- assert sink.statuses["run-timeout"] == "failed"
- assert agent_cancelled is True
- assert shell_client.closed is True
-
-
-def test_runner_does_not_classify_nested_timeout_as_agent_limit(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- assert agent_run_id == "run-provider-timeout"
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- raise TimeoutError("provider timed out")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())
- sink = InMemoryRunEventSink()
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(TimeoutError, match="provider timed out"):
- await AgentRunRunner(
- sink=sink,
- request=_request(),
- run_id="run-provider-timeout",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- run_timeout_seconds=1,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-provider-timeout"][-1]
- assert isinstance(terminal, RunFailedEvent)
- assert terminal.data.error == "provider timed out"
- assert terminal.data.error_type is None
- assert sink.statuses["run-provider-timeout"] == "failed"
-
-
-def test_runner_captures_interrupted_history_when_task_is_cancelled(monkeypatch: pytest.MonkeyPatch) -> None:
- partial_streamed = asyncio.Event()
- stored_history = [
- ModelRequest(parts=[UserPromptPart(content="old user")]),
- ModelResponse(parts=[TextPart(content="old assistant")]),
- ]
+async def test_timeout_releases_resource_and_preserves_snapshot(monkeypatch):
+ commands = Commands()
+ backend = Backend(commands)
- async def stream_response(_messages: list[ModelMessage], _info: object) -> AsyncIterator[str]:
- yield "partial"
- _ = partial_streamed.set()
+ async def stream(messages, info):
await asyncio.Event().wait()
+ yield "unreachable"
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- return FunctionModel(stream_function=stream_response)
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request("current user", include_history=True)
- request.session_snapshot = _history_session_snapshot(stored_history)
- sink = InMemoryRunEventSink()
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))
+ runner, sink = run_runner(request(*runtime_specs()), services, monkeypatch, stream, timeout=0.05)
+ with pytest.raises(UsageLimitExceeded):
+ await runner.run()
+ assert backend.released == 1
+ terminal = sink.events["test"][-1]
+ assert isinstance(terminal, RunFailedEvent)
+ assert terminal.data.error_type == RunFailureType.AGENT_RUN_LIMIT_EXCEEDED
+ assert terminal.data.session_snapshot.layers["shell"]["job_ids"] == []
+
+
+async def test_bad_configuration_prevents_resource_acquisition(monkeypatch):
+ commands = Commands()
+ backend = Backend(commands)
+
+ async def stream(messages, info):
+ raise AssertionError("Model I/O must not happen")
+ yield "unreachable"
+
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))
+ runner, sink = run_runner(
+ request(*runtime_specs(), RunLayerSpec(name="tools", config={"execution_context": "missing"})),
+ services,
+ monkeypatch,
+ stream,
+ )
+ with pytest.raises(ValueError, match="reference"):
+ await runner.run()
+ assert backend.acquired == 0
+ assert isinstance(sink.events["test"][-1], RunFailedEvent)
- async def scenario() -> AgentRunRunner:
- async with httpx.AsyncClient() as client:
- runner = AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-cancel-history",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- )
- task = asyncio.create_task(runner.run())
- await asyncio.wait_for(partial_streamed.wait(), timeout=1)
- task.cancel()
- with pytest.raises(asyncio.CancelledError):
- await task
- return runner
-
- runner = asyncio.run(scenario())
-
- assert runner.terminal_session_snapshot is not None
- assert all(layer.lifecycle_state is LifecycleState.SUSPENDED for layer in runner.terminal_session_snapshot.layers)
- _assert_interrupted_history(runner.terminal_session_snapshot, stored_history)
-
-
-def test_runner_emits_deferred_tool_call_and_persists_pending_history(monkeypatch: pytest.MonkeyPatch) -> None:
- captured_output_types: list[object] = []
- captured_user_prompts: list[object] = []
- captured_messages = _install_fake_message_capture(monkeypatch)
- pending_tool_call = ToolCallPart(
- tool_name="ask_human",
- args={
- "question": "Which deployment window should we use?",
- "fields": [{"type": "paragraph", "name": "window", "label": "Deployment window"}],
- },
- tool_call_id="tool-call-1",
- )
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, user_prompt: object, **kwargs: object) -> FakeAgentRunResult:
- captured_user_prompts.append(user_prompt)
- assert kwargs["deferred_tool_results"] is None
- messages: list[ModelMessage] = [
- ModelRequest(parts=[UserPromptPart(content="current user")]),
- ModelResponse(parts=[pending_tool_call]),
- ]
- captured_messages.extend(messages)
- return FakeAgentRunResult(DeferredToolRequests(calls=[pending_tool_call]))
+async def test_invalid_output_schema_fails_before_resource_and_model_io(monkeypatch):
+ backend = Backend(Commands())
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:
- del model, tools
- captured_output_types.append(output_type)
- return FakeAgent()
+ async def stream(messages, info):
+ pytest.fail("invalid output schema must not reach the model")
+ yield "unreachable"
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
- request = _request("current user", include_history=True, include_ask_human=True)
- sink = InMemoryRunEventSink()
+ async with httpx.AsyncClient() as client:
+ services = Services(client, client, runtime_backend_profile=RuntimeBackendProfile(None, backend))
+ runner, sink = run_runner(
+ request(
+ *runtime_specs(),
+ RunLayerSpec(name="output", config={"json_schema": {"type": "object", "required": "invalid"}}),
+ ),
+ services,
+ monkeypatch,
+ stream,
+ )
+ with pytest.raises(ValueError, match="required"):
+ await runner.run()
+ assert backend.acquired == 0
+ assert isinstance(sink.events["test"][-1], RunFailedEvent)
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-ask-human"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert captured_user_prompts == ["current user"]
- assert any(item is DeferredToolRequests for item in cast(Iterable[object], captured_output_types[0]))
- assert terminal.data.output is None
- assert terminal.data.deferred_tool_call is not None
- assert terminal.data.deferred_tool_call.tool_call_id == "tool-call-1"
- assert terminal.data.deferred_tool_call.tool_name == "ask_human"
- assert terminal.data.deferred_tool_call.args == {
- "title": None,
- "question": "Which deployment window should we use?",
- "markdown": None,
- "fields": [
- {
- "type": "paragraph",
- "name": "window",
- "label": "Deployment window",
- "required": False,
- "placeholder": None,
- "default": None,
- }
- ],
- "actions": [{"id": "submit", "label": "Submit", "style": "primary"}],
- "urgency": "normal",
- }
- saved_history = _history_messages_from_snapshot(terminal.data.session_snapshot)
- assert isinstance(saved_history[-1], ModelResponse)
- assert saved_history[-1].parts == [pending_tool_call]
-
-
-def test_runner_resumes_with_deferred_tool_results_and_no_user_prompt(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_user_prompts: list[object] = []
- seen_deferred_results: list[object] = []
- captured_messages = _install_fake_message_capture(monkeypatch)
- pending_tool_call = ToolCallPart(
- tool_name="ask_human",
- args={"question": "Need approval"},
- tool_call_id="tool-call-1",
- )
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, user_prompt: object, **kwargs: object) -> FakeAgentRunResult:
- seen_user_prompts.append(user_prompt)
- seen_deferred_results.append(kwargs.get("deferred_tool_results"))
- if kwargs.get("deferred_tool_results") is None:
- messages: list[ModelMessage] = [
- ModelRequest(parts=[UserPromptPart(content="current user")]),
- ModelResponse(parts=[pending_tool_call]),
- ]
- captured_messages.extend(messages)
- return FakeAgentRunResult(DeferredToolRequests(calls=[pending_tool_call]))
-
- deferred_tool_results = cast(DeferredToolResults, kwargs["deferred_tool_results"])
- assert deferred_tool_results is not None
- submitted_result = cast(dict[str, object], deferred_tool_results.calls["tool-call-1"])
- assert submitted_result["status"] == "submitted"
- message_history = cast(list[ModelMessage], kwargs["message_history"])
- messages = [
- *message_history,
- ModelRequest(
- parts=[
- ToolReturnPart(
- tool_name="ask_human",
- content={"status": "submitted", "values": {"comment": "Ship it"}},
- tool_call_id="tool-call-1",
- )
- ]
- ),
- ModelResponse(parts=[TextPart(content="done after human")]),
- ]
- captured_messages.extend(messages)
- return FakeAgentRunResult("done after human")
[email protected]("user", ["hello", ""])
+async def test_knowledge_user_context_is_captured_in_history_and_restored_cache(monkeypatch, user):
+ calls = []
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:
- del model, tools, output_type
- return FakeAgent()
+ def handler(request):
+ calls.append(request)
+ return httpx.Response(200, json={"results": [], "usage": {}})
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
- request = _request("current user", include_history=True, include_ask_human=True)
- sink = InMemoryRunEventSink()
+ async def stream(messages, info):
+ user_contents = [
+ p.content for m in messages if isinstance(m, ModelRequest) for p in m.parts if isinstance(p, UserPromptPart)
+ ]
+ assert any("Knowledge retrieval results" in str(content) for content in user_contents)
+ yield "done"
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human-initial",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- initial_terminal = sink.events["run-ask-human-initial"][-1]
- assert isinstance(initial_terminal, RunSucceededEvent)
-
- resumed_request = request.model_copy(deep=True)
- resumed_request.session_snapshot = initial_terminal.data.session_snapshot
- resumed_request.deferred_tool_results = DeferredToolResultsPayload.model_validate(
+ knowledge = RunLayerSpec(
+ name="knowledge",
+ config={
+ "sets": [
{
- "calls": {
- "tool-call-1": {
- "status": "submitted",
- "action": {"id": "submit", "label": "Submit"},
- "values": {"comment": "Ship it"},
- }
- }
+ "id": "support",
+ "name": "Support",
+ "datasets": [{"id": "dataset"}],
+ "query": {"mode": "user_query", "value": "release"},
+ "retrieval": {"mode": "multiple", "top_k": 4},
}
- )
-
- await AgentRunRunner(
- sink=sink,
- request=resumed_request,
- run_id="run-ask-human-resume",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- resumed_terminal = sink.events["run-ask-human-resume"][-1]
- assert isinstance(resumed_terminal, RunSucceededEvent)
- assert resumed_terminal.data.output == "done after human"
- assert resumed_terminal.data.deferred_tool_call is None
- assert seen_user_prompts == ["current user", None]
- assert seen_deferred_results[0] is None
- assert seen_deferred_results[1] is not None
-
-
-def test_runner_can_emit_second_deferred_tool_call_after_resume(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_user_prompts: list[object] = []
- captured_messages = _install_fake_message_capture(monkeypatch)
- first_pending_tool_call = ToolCallPart(
- tool_name="ask_human",
- args={"question": "Need deployment owner"},
- tool_call_id="tool-call-1",
- )
- second_pending_tool_call = ToolCallPart(
- tool_name="ask_human",
- args={"question": "Need final go-live confirmation"},
- tool_call_id="tool-call-2",
- )
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, user_prompt: object, **kwargs: object) -> FakeAgentRunResult:
- seen_user_prompts.append(user_prompt)
- deferred_tool_results = kwargs.get("deferred_tool_results")
- if deferred_tool_results is None:
- messages: list[ModelMessage] = [
- ModelRequest(parts=[UserPromptPart(content="current user")]),
- ModelResponse(parts=[first_pending_tool_call]),
- ]
- captured_messages.extend(messages)
- return FakeAgentRunResult(DeferredToolRequests(calls=[first_pending_tool_call]))
-
- message_history = cast(list[ModelMessage], kwargs["message_history"])
- messages = [
- *message_history,
- ModelRequest(
- parts=[
- ToolReturnPart(
- tool_name="ask_human",
- content={"status": "submitted", "values": {"owner": "ops"}},
- tool_call_id="tool-call-1",
- )
- ]
- ),
- ModelResponse(parts=[second_pending_tool_call]),
]
- captured_messages.extend(messages)
- return FakeAgentRunResult(DeferredToolRequests(calls=[second_pending_tool_call]))
-
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:
- del model, tools, output_type
- return FakeAgent()
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
- request = _request("current user", include_history=True, include_ask_human=True)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human-turn-1",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- first_terminal = sink.events["run-ask-human-turn-1"][-1]
- assert isinstance(first_terminal, RunSucceededEvent)
-
- resumed_request = request.model_copy(deep=True)
- resumed_request.session_snapshot = first_terminal.data.session_snapshot
- resumed_request.deferred_tool_results = DeferredToolResultsPayload.model_validate(
- {
- "calls": {
- "tool-call-1": {
- "status": "submitted",
- "action": {"id": "submit", "label": "Submit"},
- "values": {"owner": "ops"},
- }
- }
- }
- )
-
- await AgentRunRunner(
- sink=sink,
- request=resumed_request,
- run_id="run-ask-human-turn-2",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- second_terminal = sink.events["run-ask-human-turn-2"][-1]
- assert isinstance(second_terminal, RunSucceededEvent)
- assert second_terminal.data.output is None
- assert second_terminal.data.deferred_tool_call is not None
- assert second_terminal.data.deferred_tool_call.tool_call_id == "tool-call-2"
- assert seen_user_prompts == ["current user", None]
- saved_history = _history_messages_from_snapshot(second_terminal.data.session_snapshot)
- assert isinstance(saved_history[1], ModelResponse)
- assert saved_history[1].parts == [first_pending_tool_call]
- assert isinstance(saved_history[2], ModelRequest)
- assert len(saved_history[2].parts) == 1
- assert isinstance(saved_history[2].parts[0], ToolReturnPart)
- assert saved_history[2].parts[0].tool_name == "ask_human"
- assert saved_history[2].parts[0].tool_call_id == "tool-call-1"
- assert saved_history[2].parts[0].content == {"status": "submitted", "values": {"owner": "ops"}}
- assert isinstance(saved_history[3], ModelResponse)
- assert saved_history[3].parts == [second_pending_tool_call]
-
-
-def test_runner_rejects_deferred_tool_call_without_history_layer(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- return FakeAgentRunResult(
- DeferredToolRequests(
- calls=[
- ToolCallPart(tool_name="ask_human", args={"question": "Need owner"}, tool_call_id="tool-call-1")
- ]
- )
- )
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())
- request = _request("current user", include_history=False, include_ask_human=True)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError,
- match="ask_human deferred tool requests require a 'history' layer so the pending tool call can be resumed",
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human-no-history",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-ask-human-no-history"]] == ["run_started", "run_failed"]
-
-
-def test_runner_rejects_resume_with_deferred_tool_results_without_history_layer(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- agent_run_called = False
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- nonlocal agent_run_called
- agent_run_called = True
- return FakeAgentRunResult("unexpected")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())
- request = _request("current user", include_history=False, include_ask_human=True)
- request.deferred_tool_results = DeferredToolResultsPayload.model_validate(
- {
- "calls": {
- "tool-call-1": {
- "status": "submitted",
- "action": {"id": "submit", "label": "Submit"},
- "values": {"owner": "ops"},
- }
- }
- }
+ },
)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError,
- match="Deferred tool results require a 'history' layer with prior message history",
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human-resume-no-history",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert agent_run_called is False
- assert [event.type for event in sink.events["run-ask-human-resume-no-history"]] == ["run_started", "run_failed"]
-
-
-def test_runner_rejects_multiple_deferred_tool_calls(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- return FakeAgentRunResult(
- DeferredToolRequests(
- calls=[
- ToolCallPart(tool_name="ask_human", args={"question": "One"}, tool_call_id="tool-call-1"),
- ToolCallPart(tool_name="ask_human", args={"question": "Two"}, tool_call_id="tool-call-2"),
- ]
- )
- )
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())
- request = _request("current user", include_history=True, include_ask_human=True)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(ValueError, match="supports exactly one deferred call per run"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human-multi",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-ask-human-multi"]] == ["run_started", "run_failed"]
-
-
-def test_runner_rejects_deferred_approval_requests(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeAgentRunResult:
- return FakeAgentRunResult(
- DeferredToolRequests(
- approvals=[
- ToolCallPart(
- tool_name="ask_human", args={"question": "Need approval"}, tool_call_id="tool-call-1"
- )
- ]
- )
- )
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *args, **kwargs: FakeAgent())
- request = _request("current user", include_history=True, include_ask_human=True)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(ValueError, match="does not support approval requests"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-ask-human-approval",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-ask-human-approval"]] == ["run_started", "run_failed"]
-
-
-def test_runner_passes_dynamic_dify_plugin_tools_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_tools: list[Tool[object]] = []
-
- async def plugin_tool() -> str:
- return "tool"
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- async def fake_get_tools(
- self: DifyPluginToolsLayer,
- *,
- http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- assert self.config.tools[0].tool_name == "web_search"
- assert http_client.is_closed is False
- assert dify_api_http_client.is_closed is False
- return [Tool(plugin_tool, name="web_search")]
-
- class FakeResult:
- output: str = "done"
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeResult:
- return FakeResult()
-
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:
- del model, output_type
- seen_tools.extend(tools)
- return FakeAgent()
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
-
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="tools",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=_prepared_plugin_tool_parameters(),
- parameters_json_schema=_prepared_plugin_tool_schema(),
- )
- ]
- ),
- ),
- ]
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+ services = Services(client, client)
+ first, _ = run_runner(request(knowledge, user=user), services, monkeypatch, stream)
+ await first.run()
+ snapshot = first.terminal_session_snapshot
+ saved = history.State.model_validate(snapshot.layers["history"])
+ assert any(
+ "Knowledge retrieval results" in str(p.content)
+ for m in saved.messages
+ if isinstance(m, ModelRequest)
+ for p in m.parts
+ if isinstance(p, UserPromptPart)
)
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-tools",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [tool.name for tool in seen_tools] == ["web_search"]
- terminal = sink.events["run-tools"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert terminal.data.output == "done"
-
-
-def test_runner_passes_dynamic_dify_knowledge_tools_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_tools: list[Tool[object]] = []
-
- async def knowledge_tool() -> str:
- return "knowledge"
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- async def fake_get_tools(self: DifyKnowledgeBaseLayer, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:
- assert self.config.sets[0].dataset_ids == ["dataset-1"]
- assert http_client.headers.get("X-Test-Client") == "dify-api"
- return [Tool(knowledge_tool, name="knowledge_base_search")]
-
- class FakeResult:
- output: str = "done"
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeResult:
- return FakeResult()
-
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:
- del model, output_type
- seen_tools.extend(tools)
- return FakeAgent()
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyKnowledgeBaseLayer, "get_tools", fake_get_tools)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
-
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- app_id="app-1",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="knowledge",
- type=DIFY_KNOWLEDGE_BASE_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyKnowledgeBaseLayerConfig.model_validate(
- {
- "sets": [
- {
- "id": "support",
- "name": "Support KB",
- "datasets": [{"id": "dataset-1"}],
- "query": {"mode": "generated_query"},
- "retrieval": {"mode": "multiple", "top_k": 4},
- }
- ],
- }
- ),
- ),
- ]
+ second, _ = run_runner(
+ request(knowledge, snapshot=snapshot, user=user), services, monkeypatch, stream, run_id="second"
)
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with (
- httpx.AsyncClient() as plugin_client,
- httpx.AsyncClient(headers={"X-Test-Client": "dify-api"}) as dify_api_client,
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-knowledge-tools",
- plugin_daemon_http_client=plugin_client,
- dify_api_http_client=dify_api_client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [tool.name for tool in seen_tools] == ["knowledge_base_search"]
-
-
-def test_runner_passes_dynamic_dify_core_tools_to_agent(monkeypatch: pytest.MonkeyPatch) -> None:
- seen_tools: list[Tool[object]] = []
-
- async def core_tool() -> str:
- return "core"
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- async def fake_get_tools(self: DifyCoreToolsLayer, *, http_client: httpx.AsyncClient) -> list[Tool[object]]:
- assert self.config.tools[0].provider_type == "builtin"
- assert self.config.tools[0].tool_name == "draft_message"
- assert http_client.headers.get("X-Test-Client") == "dify-api"
- return [Tool(core_tool, name="draft_message")]
-
- class FakeResult:
- output: str = "done"
+ await second.run()
+ assert len(calls) == 1
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> FakeResult:
- return FakeResult()
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> FakeAgent:
- del model, output_type
- seen_tools.extend(tools)
- return FakeAgent()
[email protected]("user", ["", ["", " "]])
+async def test_empty_current_user_content_fails_before_model_io(monkeypatch, user):
+ async def stream(messages, info):
+ pytest.fail("blank user input must not reach the model")
+ yield "unreachable"
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyCoreToolsLayer, "get_tools", fake_get_tools)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
-
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_id="user-1",
- user_from="account",
- app_id="app-1",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="core-tools",
- type=DIFY_CORE_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyCoreToolsLayerConfig(
- tools=[
- DifyCoreToolConfig(
- provider_type="builtin",
- provider_id="langgenius/dify-gmail/dify-gmail",
- tool_name="draft_message",
- credential_id="credential-1",
- parameters_json_schema={"type": "object", "properties": {}, "required": []},
- )
- ]
- ),
- ),
- ]
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with (
- httpx.AsyncClient() as plugin_client,
- httpx.AsyncClient(headers={"X-Test-Client": "dify-api"}) as dify_api_client,
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-core-tools",
- plugin_daemon_http_client=plugin_client,
- dify_api_http_client=dify_api_client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [tool.name for tool in seen_tools] == ["draft_message"]
-
-
-def test_runner_rejects_duplicate_tool_names_across_dynamic_tool_layers(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- create_agent_called = False
-
- async def duplicate_tool() -> str:
- return "tool"
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- async def fake_get_tools(
- _self: DifyPluginToolsLayer,
- *,
- http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- assert http_client.is_closed is False
- assert dify_api_http_client.is_closed is False
- return [Tool(duplicate_tool, name="shared_tool")]
-
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> object:
- del model, tools, output_type
- nonlocal create_agent_called
- create_agent_called = True
- raise AssertionError("create_agent should not be called when duplicate tool names are detected")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
-
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="tools-1",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=_prepared_plugin_tool_parameters(),
- parameters_json_schema=_prepared_plugin_tool_schema(),
- )
- ]
- ),
- ),
- RunLayerSpec(
- name="tools-2",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search_two",
- credential_type="api-key",
- parameters=_prepared_plugin_tool_parameters(),
- parameters_json_schema=_prepared_plugin_tool_schema(),
- )
- ]
- ),
- ),
- ]
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError,
- match="unique tool names across all layers, got duplicates: shared_tool",
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-duplicate-tools",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert create_agent_called is False
- assert [event.type for event in sink.events["run-duplicate-tools"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-duplicate-tools"] == "failed"
-
-
-def test_runner_rejects_duplicate_tool_names_between_static_and_dynamic_tools(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- create_agent_called = False
-
- def web_search(query: str) -> str:
- return query
-
- async def dynamic_duplicate_tool() -> str:
- return "tool"
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- async def fake_get_tools(
- _self: DifyPluginToolsLayer,
- *,
- http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- assert http_client.is_closed is False
- assert dify_api_http_client.is_closed is False
- return [Tool(dynamic_duplicate_tool, name="web_search")]
-
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> object:
- del model, tools, output_type
- nonlocal create_agent_called
- create_agent_called = True
- raise AssertionError("create_agent should not be called when duplicate tool names are detected")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
-
- static_tools_provider = LayerProvider.from_factory(
- layer_type=StaticToolsTestLayer,
- create=lambda _config: StaticToolsTestLayer(tool_entries=(web_search,)),
- )
- layer_providers = (*create_default_layer_providers(), static_tools_provider)
-
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(name="static-tools", type=cast(str, StaticToolsTestLayer.type_id)),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="tools",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=_prepared_plugin_tool_parameters(),
- parameters_json_schema=_prepared_plugin_tool_schema(),
- )
- ]
- ),
- ),
- ]
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError,
- match="unique tool names across all layers, got duplicates: web_search",
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-static-dynamic-duplicate-tools",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=layer_providers,
- ).run()
-
- asyncio.run(scenario())
-
- assert create_agent_called is False
- assert [event.type for event in sink.events["run-static-dynamic-duplicate-tools"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-static-dynamic-duplicate-tools"] == "failed"
-
-
-def test_runner_rejects_duplicate_tool_names_between_shell_and_other_layers(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- create_agent_called = False
- shell_client = FakeRunnerShellctlClient()
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- async def fake_get_tools(
- _self: DifyPluginToolsLayer,
- *,
- http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- assert http_client.is_closed is False
- assert dify_api_http_client.is_closed is False
-
- async def duplicate_shell_run() -> str:
- return "tool"
-
- return [Tool(duplicate_shell_run, name="shell_run")]
-
- def fake_create_agent(model: object, *, tools: list[Tool[object]], output_type: object) -> object:
- del model, tools, output_type
- nonlocal create_agent_called
- create_agent_called = True
- raise AssertionError("create_agent should not be called when duplicate tool names are detected")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", fake_create_agent)
-
- runtime_backend_profile = RuntimeBackendProfile(
- home_snapshots=cast(HomeSnapshotBackend, object()),
- execution_bindings=FakeRunnerExecutionBindingBackend(shell_client),
- )
- layer_providers = create_default_layer_providers(runtime_backend_profile=runtime_backend_profile)
-
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- agent_id="agent-1",
- agent_config_version_id="config-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name="runtime",
- type=DIFY_RUNTIME_LAYER_TYPE_ID,
- config=DifyRuntimeLayerConfig(backend_binding_ref="binding-1"),
- ),
- RunLayerSpec(
- name="shell",
- type=DIFY_SHELL_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context", "runtime": "runtime"},
- config=DifyShellLayerConfig(),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="tools",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=_prepared_plugin_tool_parameters(),
- parameters_json_schema=_prepared_plugin_tool_schema(),
- )
- ]
- ),
- ),
- ]
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError,
- match="unique tool names across all layers, got duplicates: shell_run",
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-shell-duplicate-tools",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=layer_providers,
- ).run()
-
- asyncio.run(scenario())
-
- assert create_agent_called is False
- assert shell_client.delete_calls == []
- assert shell_client.closed is True
- assert [event.type for event in sink.events["run-shell-duplicate-tools"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-shell-duplicate-tools"] == "failed"
-
-
-def test_runner_passes_system_prompt_as_run_instructions_without_history_layer(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- model = RecordingTestModel(custom_output_text="done")
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return model # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=_request("current user"),
- run_id="run-no-history",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model.seen_instructions[0] == ["system"]
- request_parts = _flatten_message_parts(model.seen_requests[0])
- assert len(request_parts) == 1
- assert isinstance(request_parts[0], UserPromptPart)
- assert request_parts[0].content == "current user"
- terminal = sink.events["run-no-history"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert [layer.name for layer in terminal.data.session_snapshot.layers] == [
- "prompt",
- "execution_context",
- DIFY_AGENT_MODEL_LAYER_ID,
- ]
-
-
-def test_runner_passes_stored_history_with_current_instructions_and_replaces_full_history(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- model = RecordingTestModel(custom_output_text="done")
- stored_history = [
- ModelRequest(parts=[UserPromptPart(content="old user")]),
- ModelResponse(parts=[TextPart(content="old assistant")]),
- ]
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return model # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request("current user", include_history=True)
- request.session_snapshot = _history_session_snapshot(stored_history)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-history",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model.seen_instructions[0] == ["system"]
- request_parts = _flatten_message_parts(model.seen_requests[0])
- assert isinstance(request_parts[0], UserPromptPart)
- assert request_parts[0].content == "old user"
- assert isinstance(request_parts[1], TextPart)
- assert request_parts[1].content == "old assistant"
- assert isinstance(request_parts[2], UserPromptPart)
- assert request_parts[2].content == "current user"
-
- terminal = sink.events["run-history"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- saved_history = _history_messages_from_snapshot(terminal.data.session_snapshot)
- assert saved_history[:2] == stored_history
- assert isinstance(saved_history[2], ModelRequest)
- assert len(saved_history[2].parts) == 1
- assert isinstance(saved_history[2].parts[0], UserPromptPart)
- assert saved_history[2].parts[0].content == "current user"
- assert isinstance(saved_history[3], ModelResponse)
- assert len(saved_history[3].parts) == 1
- assert isinstance(saved_history[3].parts[0], TextPart)
- assert saved_history[3].parts[0].content == "done"
- assert all(not any(isinstance(part, SystemPromptPart) for part in message.parts) for message in saved_history)
- assert all(not isinstance(message, ModelRequest) or message.instructions is None for message in saved_history)
-
-
-def test_runner_with_empty_history_layer_uses_instructions_and_saves_full_history(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- model = RecordingTestModel(custom_output_text="done")
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return model # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request("current user", include_history=True)
- request.session_snapshot = _history_session_snapshot([])
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-empty-history",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model.seen_instructions[0] == ["system"]
- request_parts = _flatten_message_parts(model.seen_requests[0])
- assert len(request_parts) == 1
- assert isinstance(request_parts[0], UserPromptPart)
- assert request_parts[0].content == "current user"
-
- terminal = sink.events["run-empty-history"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- saved_history = _history_messages_from_snapshot(terminal.data.session_snapshot)
- assert isinstance(saved_history[0], ModelRequest)
- assert len(saved_history[0].parts) == 1
- assert isinstance(saved_history[0].parts[0], UserPromptPart)
- assert saved_history[0].parts[0].content == "current user"
- assert isinstance(saved_history[1], ModelResponse)
- assert len(saved_history[1].parts) == 1
- assert isinstance(saved_history[1].parts[0], TextPart)
- assert saved_history[1].parts[0].content == "done"
- assert all(not any(isinstance(part, SystemPromptPart) for part in message.parts) for message in saved_history)
- assert all(not isinstance(message, ModelRequest) or message.instructions is None for message in saved_history)
-
-
-def test_runner_failure_with_history_layer_captures_interrupted_history(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- stored_history = [
- ModelRequest(parts=[UserPromptPart(content="old user")]),
- ModelResponse(parts=[TextPart(content="old assistant")]),
- ]
-
- async def stream_response(_messages: list[ModelMessage], _info: object) -> AsyncIterator[str]:
- yield "partial"
- raise RuntimeError("boom")
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return FunctionModel(stream_function=stream_response)
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request("current user", include_history=True)
- request.session_snapshot = _history_session_snapshot(stored_history)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(RuntimeError, match="boom"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-history-failure",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- event_types = [event.type for event in sink.events["run-history-failure"]]
- assert event_types[0] == "run_started"
- assert sink.statuses["run-history-failure"] == "failed"
- terminal = sink.events["run-history-failure"][-1]
- assert isinstance(terminal, RunFailedEvent)
- assert terminal.data.session_snapshot is not None
- _assert_interrupted_history(terminal.data.session_snapshot, stored_history)
- assert request.session_snapshot is not None
- assert _history_messages_from_snapshot(request.session_snapshot) == stored_history
-
-
-def test_runner_preserves_history_when_agent_fails_before_capture_is_bound(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- stored_history = [
- ModelRequest(parts=[UserPromptPart(content="old user")]),
- ModelResponse(parts=[TextPart(content="old assistant")]),
- ]
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="unused") # pyright: ignore[reportReturnType]
-
- class FakeAgent:
- async def run(self, *_args: object, **_kwargs: object) -> None:
- raise RuntimeError("boom before capture")
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr("dify_agent.runtime.runner.create_agent", lambda *_args, **_kwargs: FakeAgent())
- request = _request("current user", include_history=True)
- request.session_snapshot = _history_session_snapshot(stored_history)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(RuntimeError, match="boom before capture"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-history-empty-capture",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-history-empty-capture"][-1]
- assert isinstance(terminal, RunFailedEvent)
- assert terminal.data.session_snapshot is not None
- assert _history_messages_from_snapshot(terminal.data.session_snapshot) == stored_history
-
-
-def test_runner_persists_usage_limit_failure_type_in_event_and_status(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- runner = AgentRunRunner(
- sink=sink,
- request=_request(),
- run_id="run-limit",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- )
-
- async def exceed_limit() -> RunSuccessOutcome:
- raise UsageLimitExceeded("The next request would exceed the request_limit of 500")
-
- monkeypatch.setattr(runner, "_run_agent", exceed_limit)
- with pytest.raises(UsageLimitExceeded):
- await runner.run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-limit"][-1]
- assert isinstance(terminal, RunFailedEvent)
- assert terminal.data.error_type is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED
- assert sink.statuses["run-limit"] == "failed"
- assert sink.error_types["run-limit"] is RunFailureType.AGENT_RUN_LIMIT_EXCEEDED
-
-
-def test_runner_applies_on_exit_overrides_to_success_snapshot(monkeypatch: pytest.MonkeyPatch) -> None:
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request(
- on_exit=LayerExitSignals(
- default=ExitIntent.SUSPEND,
- layers={"prompt": ExitIntent.DELETE, DIFY_AGENT_MODEL_LAYER_ID: ExitIntent.DELETE},
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-exit",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-exit"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert {layer.name: layer.lifecycle_state for layer in terminal.data.session_snapshot.layers} == {
- "prompt": LifecycleState.CLOSED,
- "execution_context": LifecycleState.SUSPENDED,
- DIFY_AGENT_MODEL_LAYER_ID: LifecycleState.CLOSED,
- }
-
-
-def test_runner_requires_model_layer() -> None:
- request = _request(llm_layer_name="not-llm")
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="Missing required"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-missing-model",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-missing-model"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-missing-model"] == "failed"
-
-
-def test_runner_passes_output_layer_spec_to_agent_and_serializes_structured_result(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- model = TestModel(
- custom_output_args={
- "title": "Database outage",
- "severity": "high",
- "actions": ["page on-call", "open incident bridge"],
- }
- )
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return model # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request(
- output_config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {
- "title": {"type": "string"},
- "severity": {"type": "string", "enum": ["low", "medium", "high"]},
- "actions": {"type": "array", "items": {"type": "string"}},
- },
- "required": ["title", "severity", "actions"],
- "additionalProperties": False,
- },
- description="Structured incident summary returned by the agent.",
- strict=True,
- )
- )
- sink = InMemoryRunEventSink()
- expected_snapshot_layer_names = [
- "prompt",
- "execution_context",
- DIFY_AGENT_MODEL_LAYER_ID,
- DIFY_AGENT_OUTPUT_LAYER_ID,
- ]
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-structured-output",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- first_terminal = sink.events["run-structured-output"][-1]
- assert isinstance(first_terminal, RunSucceededEvent)
-
- resumed_request = request.model_copy(deep=True)
- resumed_request.session_snapshot = first_terminal.data.session_snapshot
-
- await AgentRunRunner(
- sink=sink,
- request=resumed_request,
- run_id="run-structured-output-resume",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model.last_model_request_parameters is not None
- assert len(model.last_model_request_parameters.output_tools) == 1
- output_tool = model.last_model_request_parameters.output_tools[0]
- assert output_tool.name == "final_output"
- assert output_tool.description == "Structured incident summary returned by the agent."
- assert output_tool.parameters_json_schema["type"] == "object"
- assert output_tool.parameters_json_schema["title"] == "final_output"
- assert output_tool.parameters_json_schema["properties"] == {
- "title": {"type": "string"},
- "severity": {"type": "string", "enum": ["low", "medium", "high"]},
- "actions": {"type": "array", "items": {"type": "string"}},
- }
- assert output_tool.parameters_json_schema["required"] == ["title", "severity", "actions"]
- assert output_tool.parameters_json_schema["additionalProperties"] is False
- terminal = sink.events["run-structured-output"][-1]
- resumed_terminal = sink.events["run-structured-output-resume"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert isinstance(resumed_terminal, RunSucceededEvent)
- assert terminal.data.output == {
- "title": "Database outage",
- "severity": "high",
- "actions": ["page on-call", "open incident bridge"],
- }
- assert resumed_terminal.data.output == terminal.data.output
- assert [layer.name for layer in terminal.data.session_snapshot.layers] == expected_snapshot_layer_names
- assert [layer.name for layer in resumed_terminal.data.session_snapshot.layers] == expected_snapshot_layer_names
- assert all(layer.lifecycle_state is LifecycleState.SUSPENDED for layer in terminal.data.session_snapshot.layers)
- assert all(
- layer.lifecycle_state is LifecycleState.SUSPENDED for layer in resumed_terminal.data.session_snapshot.layers
- )
-
-
-def test_runner_retries_invalid_structured_output_and_eventually_succeeds(monkeypatch: pytest.MonkeyPatch) -> None:
- model = SequenceOutputTestModel(
- outputs=[
- {"title": "Database outage", "severity": "high", "actions": "page on-call"},
- {"title": "Database outage", "severity": "high", "actions": ["page on-call"]},
- ]
- )
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return model # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request(
- output_config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {
- "title": {"type": "string"},
- "severity": {"type": "string", "enum": ["low", "medium", "high"]},
- "actions": {"type": "array", "items": {"type": "string"}},
- },
- "required": ["title", "severity", "actions"],
- "additionalProperties": False,
- },
- description="Structured incident summary returned by the agent.",
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-output-retry-success",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- terminal = sink.events["run-output-retry-success"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert terminal.data.output == {
- "title": "Database outage",
- "severity": "high",
- "actions": ["page on-call"],
- }
- assert model.request_count == 2
-
-
-def test_runner_fails_when_invalid_structured_output_exhausts_retries(monkeypatch: pytest.MonkeyPatch) -> None:
- model = TestModel(
- custom_output_args={
- "title": "Database outage",
- "severity": "high",
- "actions": "page on-call",
- }
- )
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- assert http_client.is_closed is False
- return model # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request(
- output_config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {
- "title": {"type": "string"},
- "severity": {"type": "string", "enum": ["low", "medium", "high"]},
- "actions": {"type": "array", "items": {"type": "string"}},
- },
- "required": ["title", "severity", "actions"],
- "additionalProperties": False,
- },
- description="Structured incident summary returned by the agent.",
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(UnexpectedModelBehavior):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-output-retry-failed",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- event_types = [event.type for event in sink.events["run-output-retry-failed"]]
- assert event_types[0] == "run_started"
- assert event_types[-1] == "run_failed"
- assert "run_succeeded" not in event_types
- assert sink.statuses["run-output-retry-failed"] == "failed"
-
-
-def test_runner_rejects_invalid_output_layer_before_model_resolution(monkeypatch: pytest.MonkeyPatch) -> None:
- model_requested = False
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- del http_client
- nonlocal model_requested
- model_requested = True
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = _request(
- output_config={
- "json_schema": _recursive_output_schema(),
- }
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match=r"Recursive \$defs refs are not supported"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-invalid-output",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model_requested is False
- assert [event.type for event in sink.events["run-invalid-output"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-invalid-output"] == "failed"
-
-
-def test_runner_rejects_misnamed_output_layer_before_model_resolution(monkeypatch: pytest.MonkeyPatch) -> None:
- model_requested = False
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name="structured-output",
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {"title": {"type": "string"}},
- "required": ["title"],
- "additionalProperties": False,
- }
- ),
- ),
- ]
- ),
- on_exit=LayerExitSignals(),
- )
- sink = InMemoryRunEventSink()
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- del http_client
- nonlocal model_requested
- model_requested = True
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="must use reserved layer name 'output'"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-misnamed-output",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model_requested is False
- assert [event.type for event in sink.events["run-misnamed-output"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-misnamed-output"] == "failed"
-
-
-def test_runner_rejects_multiple_output_layers_before_model_resolution(monkeypatch: pytest.MonkeyPatch) -> None:
- model_requested = False
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {"title": {"type": "string"}},
- "required": ["title"],
- "additionalProperties": False,
- }
- ),
- ),
- RunLayerSpec(
- name="secondary-output",
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {"summary": {"type": "string"}},
- "required": ["summary"],
- "additionalProperties": False,
- }
- ),
- ),
- ]
- ),
- on_exit=LayerExitSignals(),
- )
- sink = InMemoryRunEventSink()
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- del http_client
- nonlocal model_requested
- model_requested = True
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="Only one 'dify.output' layer is supported"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-duplicate-output",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model_requested is False
- assert [event.type for event in sink.events["run-duplicate-output"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-duplicate-output"] == "failed"
-
-
-def test_runner_rejects_reserved_output_name_with_wrong_layer_type_before_model_resolution(
- monkeypatch: pytest.MonkeyPatch,
-) -> None:
- model_requested = False
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- del http_client
- nonlocal model_requested
- model_requested = True
- return TestModel(custom_output_text="done") # pyright: ignore[reportReturnType]
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_OUTPUT_LAYER_ID,
- type="plain.prompt",
- config=PromptLayerConfig(user="not structured output"),
- ),
- ]
- ),
- on_exit=LayerExitSignals(),
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(
- AgentRunValidationError, match=r"Layer 'output' must be DifyOutputLayer, got PromptLayer"
- ):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-wrong-output-type",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert model_requested is False
- assert [event.type for event in sink.events["run-wrong-output-type"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-wrong-output-type"] == "failed"
-
-
-def test_runner_rejects_misnamed_output_layer_before_provider_checks() -> None:
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="structured-output",
- type=DIFY_OUTPUT_LAYER_TYPE_ID,
- config=DifyOutputLayerConfig(
- json_schema={
- "type": "object",
- "properties": {"title": {"type": "string"}},
- "required": ["title"],
- "additionalProperties": False,
- }
- ),
- ),
- ]
- ),
- on_exit=LayerExitSignals(),
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="must use reserved layer name 'output'"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-misnamed-output-before-providers",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=(),
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-misnamed-output-before-providers"]] == [
- "run_started",
- "run_failed",
- ]
- assert sink.statuses["run-misnamed-output-before-providers"] == "failed"
-
-
-def test_runner_rejects_unknown_on_exit_layer_id() -> None:
- request = _request(on_exit=LayerExitSignals(layers={"missing": ExitIntent.DELETE}))
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="missing"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-unknown-signal",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-unknown-signal"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-unknown-signal"] == "failed"
-
-
-def test_runner_honors_explicit_empty_layer_providers() -> None:
- request = _request()
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="plain.prompt"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-empty-providers",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=(),
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-empty-providers"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-empty-providers"] == "failed"
-
-
-def test_runner_fails_empty_user_prompts() -> None:
- request = _request("")
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-2",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-2"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-2"] == "failed"
-
-
-def test_runner_fails_blank_string_user_prompt_list() -> None:
- request = _request(["", " "])
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-3",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-3"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-3"] == "failed"
-
-
-def test_runner_rejects_reserved_llm_layer_name_with_wrong_type() -> None:
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="plain.prompt",
- config=PromptLayerConfig(user="not an llm"),
- ),
- ]
- ),
- on_exit=LayerExitSignals(),
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="DifyPluginLLMLayer"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-4",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-4"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-4"] == "failed"
-
-
-def test_runner_rejects_closed_session_snapshot_as_validation_error() -> None:
- request = _request()
- request.session_snapshot = CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(
- name="prompt",
- lifecycle_state=LifecycleState.CLOSED,
- runtime_state={},
- ),
- LayerSessionSnapshot(
- name="execution_context",
- lifecycle_state=LifecycleState.NEW,
- runtime_state={},
- ),
- LayerSessionSnapshot(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- lifecycle_state=LifecycleState.NEW,
- runtime_state={},
- ),
- ]
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="CLOSED snapshots cannot be entered"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-closed-snapshot",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-closed-snapshot"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-closed-snapshot"] == "failed"
- terminal = sink.events["run-closed-snapshot"][-1]
- assert isinstance(terminal, RunFailedEvent)
- assert request.session_snapshot is not None
- assert terminal.data.session_snapshot is None
-
-
-def test_runner_treats_missing_runtime_dependency_as_validation_error() -> None:
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(name="shell", type=DIFY_SHELL_LAYER_TYPE_ID, config=DifyShellLayerConfig()),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- ]
- )
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="Dependency 'runtime' is required"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-missing-shell-entrypoint",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-missing-shell-entrypoint"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-missing-shell-entrypoint"] == "failed"
-
-
-def test_runner_treats_invalid_shell_snapshot_offsets_as_validation_error() -> None:
- request = CreateRunRequest(
- composition=RunComposition(
- layers=[
- RunLayerSpec(
- name="prompt",
- type="plain.prompt",
- config=PromptLayerConfig(prefix="system", user="hello"),
- ),
- RunLayerSpec(name="shell", type=DIFY_SHELL_LAYER_TYPE_ID, config=DifyShellLayerConfig()),
- RunLayerSpec(
- name="execution_context",
- type=DIFY_EXECUTION_CONTEXT_LAYER_TYPE_ID,
- config=DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- ),
- ),
- RunLayerSpec(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- type="dify.plugin.llm",
- deps={"execution_context": "execution_context"},
- config=DifyPluginLLMLayerConfig(
- plugin_id="langgenius/openai",
- model_provider="openai",
- model="demo-model",
- ),
- ),
- ]
- ),
- session_snapshot=CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(name="prompt", lifecycle_state=LifecycleState.SUSPENDED, runtime_state={}),
- LayerSessionSnapshot(
- name="shell",
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={
- "session_id": "abc12ff",
- "workspace_cwd": "~/workspace/abc12ff",
- "job_ids": ["job-1"],
- "job_offsets": {"job-1": -1},
- },
- ),
- LayerSessionSnapshot(
- name="execution_context",
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={},
- ),
- LayerSessionSnapshot(
- name=DIFY_AGENT_MODEL_LAYER_ID,
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={},
- ),
- ]
- ),
- )
- sink = InMemoryRunEventSink()
-
- async def scenario() -> None:
- async with httpx.AsyncClient() as client:
- with pytest.raises(AgentRunValidationError, match="job_offsets"):
- await AgentRunRunner(
- sink=sink,
- request=request,
- run_id="run-invalid-shell-offset",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- layer_providers=create_default_layer_providers(),
- ).run()
-
- asyncio.run(scenario())
-
- assert [event.type for event in sink.events["run-invalid-shell-offset"]] == ["run_started", "run_failed"]
- assert sink.statuses["run-invalid-shell-offset"] == "failed"
-
-
-def _request_with_tool_layer(user: str) -> CreateRunRequest:
- request = _request(user, include_history=True)
- request.composition.layers.append(
- RunLayerSpec(
- name="tools",
- type=DIFY_PLUGIN_TOOLS_LAYER_TYPE_ID,
- deps={"execution_context": "execution_context"},
- config=DifyPluginToolsLayerConfig(
- tools=[
- DifyPluginToolConfig(
- plugin_id="langgenius/tools",
- provider="search",
- tool_name="web_search",
- credential_type="api-key",
- parameters=_prepared_plugin_tool_parameters(),
- parameters_json_schema=_prepared_plugin_tool_schema(),
- )
- ]
- ),
- )
- )
- return request
-
-
-def _install_tool_calling_model_and_blocking_tool(monkeypatch: pytest.MonkeyPatch, tool_started: asyncio.Event) -> None:
- async def blocking_tool(query: str) -> str:
- del query
- _ = tool_started.set()
- await asyncio.Event().wait()
- return "unreachable"
-
- async def call_web_search(_messages: list[ModelMessage], _info: object) -> AsyncIterator[DeltaToolCalls]:
- yield {
- 0: DeltaToolCall(
- name="web_search",
- json_args='{"query": "dify"}',
- tool_call_id="call-1",
- )
- }
-
- async def fake_get_tools(
- _self: DifyPluginToolsLayer,
- *,
- http_client: httpx.AsyncClient,
- dify_api_http_client: httpx.AsyncClient,
- ) -> list[Tool[object]]:
- del http_client, dify_api_http_client
- return [Tool(blocking_tool, name="web_search")]
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- del http_client, agent_run_id
- return FunctionModel(stream_function=call_web_search)
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- monkeypatch.setattr(DifyPluginToolsLayer, "get_tools", fake_get_tools)
-
-
-def test_runner_marks_unexecuted_tool_calls_when_run_is_cancelled(monkeypatch: pytest.MonkeyPatch) -> None:
- tool_started = asyncio.Event()
- _install_tool_calling_model_and_blocking_tool(monkeypatch, tool_started)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> AgentRunRunner:
- async with httpx.AsyncClient() as client:
- runner = AgentRunRunner(
- sink=sink,
- request=_request_with_tool_layer("find something"),
- run_id="run-cancel-tool-call",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- )
- task = asyncio.create_task(runner.run())
- await asyncio.wait_for(tool_started.wait(), timeout=5)
- _ = task.cancel()
- with pytest.raises(asyncio.CancelledError):
- await task
- return runner
-
- runner = asyncio.run(scenario())
-
- assert runner.terminal_session_snapshot is not None
- saved_history = _history_messages_from_snapshot(runner.terminal_session_snapshot)
- pending_response = saved_history[-1]
- assert isinstance(pending_response, ModelResponse)
- assert pending_response.state == "interrupted"
- assert [part.tool_call_id for part in pending_response.tool_calls] == ["call-1"]
-
-
-def test_runner_continues_conversation_after_a_cancelled_tool_call(monkeypatch: pytest.MonkeyPatch) -> None:
- tool_started = asyncio.Event()
- _install_tool_calling_model_and_blocking_tool(monkeypatch, tool_started)
- sink = InMemoryRunEventSink()
-
- async def scenario() -> AgentRunRunner:
- async with httpx.AsyncClient() as client:
- cancelled_runner = AgentRunRunner(
- sink=sink,
- request=_request_with_tool_layer("find something"),
- run_id="run-cancel-first",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- )
- task = asyncio.create_task(cancelled_runner.run())
- await asyncio.wait_for(tool_started.wait(), timeout=5)
- _ = task.cancel()
- with pytest.raises(asyncio.CancelledError):
- await task
-
- assert cancelled_runner.terminal_session_snapshot is not None
-
- async def answer(_messages: list[ModelMessage], _info: object) -> AsyncIterator[str]:
- yield "second answer"
-
- def fake_get_model(_self: DifyPluginLLMLayer, *, http_client: httpx.AsyncClient, agent_run_id: str):
- del http_client, agent_run_id
- return FunctionModel(stream_function=answer)
-
- monkeypatch.setattr(DifyPluginLLMLayer, "get_model", fake_get_model)
- follow_up = _request_with_tool_layer("what happened?")
- follow_up.session_snapshot = cancelled_runner.terminal_session_snapshot
- follow_up_runner = AgentRunRunner(
- sink=sink,
- request=follow_up,
- run_id="run-continue",
- plugin_daemon_http_client=client,
- dify_api_http_client=client,
- )
- await follow_up_runner.run()
- return follow_up_runner
-
- follow_up_runner = asyncio.run(scenario())
-
- terminal = sink.events["run-continue"][-1]
- assert isinstance(terminal, RunSucceededEvent)
- assert terminal.data.output == "second answer"
- assert follow_up_runner.terminal_session_snapshot is not None
- saved_history = _history_messages_from_snapshot(follow_up_runner.terminal_session_snapshot)
- interrupted_returns = [
- part
- for part in _flatten_message_parts(saved_history)
- if isinstance(part, ToolReturnPart) and part.tool_call_id == "call-1"
- ]
- assert len(interrupted_returns) == 1
- assert interrupted_returns[0].outcome == "interrupted"
+ async with httpx.AsyncClient() as client:
+ runner, sink = run_runner(request(user=user), Services(client, client), monkeypatch, stream)
+ with pytest.raises(ValueError, match="run.user_prompts must not be empty"):
+ await runner.run()
+ assert isinstance(sink.events["test"][-1], RunFailedEvent)
diff --git a/dify-agent/tests/local/dify_agent/runtime/test_runtime_history.py b/dify-agent/tests/local/dify_agent/runtime/test_runtime_history.py
deleted file mode 100644
index 43031422715..00000000000
--- a/dify-agent/tests/local/dify_agent/runtime/test_runtime_history.py
+++ /dev/null
@@ -1,169 +0,0 @@
-import asyncio
-
-import pytest
-from pydantic_ai.messages import (
- ModelRequest,
- ModelResponse,
- SystemPromptPart,
- TextPart,
- ToolCallPart,
- UserPromptPart,
-)
-
-from agenton.compositor import Compositor, LayerNode
-from agenton_collections.layers.pydantic_ai import (
- PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- PydanticAIHistoryLayer,
-)
-from dify_agent.protocol import DIFY_AGENT_HISTORY_LAYER_ID
-from dify_agent.protocol.schemas import RunComposition, RunLayerSpec
-from dify_agent.runtime.compositor_factory import create_default_layer_providers
-from dify_agent.runtime.history import (
- get_history_layer,
- replace_run_history,
- validate_history_layer_composition,
-)
-
-
-def test_default_layer_providers_include_pydantic_ai_history_layer() -> None:
- providers = create_default_layer_providers()
-
- assert PYDANTIC_AI_HISTORY_LAYER_TYPE_ID in {provider.type_id for provider in providers}
-
-
-def test_validate_history_layer_composition_accepts_absent_or_reserved_history_layer() -> None:
- validate_history_layer_composition(RunComposition(layers=[]))
- validate_history_layer_composition(
- RunComposition(
- layers=[
- RunLayerSpec(
- name=DIFY_AGENT_HISTORY_LAYER_ID,
- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- )
- ]
- )
- )
-
-
-def test_validate_history_layer_composition_rejects_multiple_history_layers() -> None:
- composition = RunComposition(
- layers=[
- RunLayerSpec(name=DIFY_AGENT_HISTORY_LAYER_ID, type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID),
- RunLayerSpec(name="secondary-history", type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID),
- ]
- )
-
- with pytest.raises(ValueError, match="Only one 'pydantic_ai.history' layer is supported"):
- validate_history_layer_composition(composition)
-
-
-def test_validate_history_layer_composition_rejects_misnamed_history_layer() -> None:
- composition = RunComposition(
- layers=[
- RunLayerSpec(name="chat-history", type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID),
- ]
- )
-
- with pytest.raises(ValueError, match="must use reserved layer name 'history'"):
- validate_history_layer_composition(composition)
-
-
-def test_validate_history_layer_composition_rejects_history_layer_dependencies() -> None:
- composition = RunComposition(
- layers=[
- RunLayerSpec(
- name=DIFY_AGENT_HISTORY_LAYER_ID,
- type=PYDANTIC_AI_HISTORY_LAYER_TYPE_ID,
- deps={"prompt": "prompt"},
- )
- ]
- )
-
- with pytest.raises(ValueError, match="does not support dependencies"):
- validate_history_layer_composition(composition)
-
-
-def test_get_history_layer_returns_optional_active_history_layer() -> None:
- compositor = Compositor([LayerNode(DIFY_AGENT_HISTORY_LAYER_ID, PydanticAIHistoryLayer)])
-
- async def scenario() -> None:
- async with compositor.enter() as run:
- history_layer = get_history_layer(run)
-
- assert isinstance(history_layer, PydanticAIHistoryLayer)
-
- asyncio.run(scenario())
-
-
-def test_replace_run_history_persists_full_history_without_instructions() -> None:
- history_layer = PydanticAIHistoryLayer()
- history_layer.replace_messages([ModelRequest(parts=[UserPromptPart(content="stale")])])
- messages = [
- ModelRequest(
- parts=[SystemPromptPart(content="Summary of previous conversation:\n\nsummary")],
- instructions="current instructions",
- ),
- ModelRequest(parts=[UserPromptPart(content="new user")]),
- ModelResponse(parts=[TextPart(content="new assistant")]),
- ]
-
- replace_run_history(history_layer, messages)
-
- persisted = history_layer.message_history
- assert len(persisted) == 3
- persisted_request = persisted[0]
- assert isinstance(persisted_request, ModelRequest)
- assert persisted_request.instructions is None
- assert persisted_request.parts == messages[0].parts
- assert persisted[1:] == messages[1:]
- source_request = messages[0]
- assert isinstance(source_request, ModelRequest)
- assert source_request.instructions == "current instructions"
-
-
-def test_replace_run_history_marks_unexecuted_tool_calls_of_an_interrupted_run() -> None:
- history_layer = PydanticAIHistoryLayer()
- messages = [
- ModelRequest(parts=[UserPromptPart(content="run a search")]),
- ModelResponse(parts=[ToolCallPart(tool_name="search", args={}, tool_call_id="call-1")]),
- ]
-
- replace_run_history(history_layer, messages, interrupted=True)
-
- persisted = history_layer.message_history
- assert len(persisted) == 2
- persisted_response = persisted[-1]
- assert isinstance(persisted_response, ModelResponse)
- assert persisted_response.state == "interrupted"
- assert persisted_response.parts == messages[1].parts
- source_response = messages[1]
- assert isinstance(source_response, ModelResponse)
- assert source_response.state == "complete"
-
-
-def test_replace_run_history_keeps_open_tool_calls_of_a_finished_run() -> None:
- history_layer = PydanticAIHistoryLayer()
- messages = [
- ModelRequest(parts=[UserPromptPart(content="ask me something")]),
- ModelResponse(parts=[ToolCallPart(tool_name="ask_human", args={}, tool_call_id="call-1")]),
- ]
-
- replace_run_history(history_layer, messages)
-
- persisted_response = history_layer.message_history[-1]
- assert isinstance(persisted_response, ModelResponse)
- assert persisted_response.state == "complete"
-
-
-def test_replace_run_history_leaves_an_interrupted_run_without_tool_calls_alone() -> None:
- history_layer = PydanticAIHistoryLayer()
- messages = [
- ModelRequest(parts=[UserPromptPart(content="hello")]),
- ModelResponse(parts=[TextPart(content="partial")]),
- ]
-
- replace_run_history(history_layer, messages, interrupted=True)
-
- persisted_response = history_layer.message_history[-1]
- assert isinstance(persisted_response, ModelResponse)
- assert persisted_response.state == "complete"
diff --git a/dify-agent/tests/local/dify_agent/server/test_app.py b/dify-agent/tests/local/dify_agent/server/test_app.py
index 8bab0a95bf2..3841cd7c662 100644
--- a/dify-agent/tests/local/dify_agent/server/test_app.py
+++ b/dify-agent/tests/local/dify_agent/server/test_app.py
@@ -6,24 +6,15 @@ import time
from typing import ClassVar
import httpx
+from dify_agent.runtime.context import Services
import pytest
from fastapi.testclient import TestClient
import dify_agent.server.app as app_module
import dify_agent.server.observability as server_observability
from dify_agent.layers.execution_context import DifyExecutionContextLayerConfig
-from dify_agent.layers.execution_context.layer import DifyExecutionContextLayer
-from dify_agent.layers.knowledge.configs import DifyKnowledgeBaseLayerConfig
-from dify_agent.layers.knowledge.layer import DifyKnowledgeBaseLayer
-from dify_agent.layers.shell import DifyShellLayerConfig
-from dify_agent.layers.shell.layer import DifyShellLayer
-from dify_agent.layers.runtime import DifyRuntimeLayerConfig
-from dify_agent.layers.runtime.layer import DifyRuntimeLayer
-from dify_agent.runtime_backend.local import LocalExecutionBindingBackend
-from dify_agent.runtime.compositor_factory import DifyAgentLayerProvider
from dify_agent.server.app import create_app, create_dify_api_inner_http_client, create_plugin_daemon_http_client
from dify_agent.server.settings import ServerSettings
-from dify_agent.storage.redis_run_store import RedisRunStore
@pytest.fixture(autouse=True)
@@ -92,7 +83,7 @@ class FakeRunScheduler:
stream_text_delta_coalescing_enabled: bool
stream_text_delta_flush_interval_seconds: float
stream_text_delta_max_chars: int
- layer_providers: tuple[DifyAgentLayerProvider, ...]
+ services: Services
plugin_daemon_http_client: FakePluginDaemonHttpClient
dify_api_http_client: FakePluginDaemonHttpClient
shutdown_called: bool
@@ -101,14 +92,12 @@ class FakeRunScheduler:
self,
*,
store: object,
- plugin_daemon_http_client: FakePluginDaemonHttpClient,
- dify_api_http_client: FakePluginDaemonHttpClient,
+ services: Services,
shutdown_grace_seconds: float,
run_timeout_seconds: float,
stream_text_delta_coalescing_enabled: bool,
stream_text_delta_flush_interval_seconds: float,
stream_text_delta_max_chars: int,
- layer_providers: tuple[DifyAgentLayerProvider, ...],
agent_observability: object | None = None,
) -> None:
self.store = store
@@ -117,9 +106,9 @@ class FakeRunScheduler:
self.stream_text_delta_coalescing_enabled = stream_text_delta_coalescing_enabled
self.stream_text_delta_flush_interval_seconds = stream_text_delta_flush_interval_seconds
self.stream_text_delta_max_chars = stream_text_delta_max_chars
- self.layer_providers = layer_providers
- self.plugin_daemon_http_client = plugin_daemon_http_client
- self.dify_api_http_client = dify_api_http_client
+ self.services = services
+ self.plugin_daemon_http_client = services.plugin_daemon_http_client
+ self.dify_api_http_client = services.dify_api_http_client
self.agent_observability = agent_observability
self.shutdown_called = False
self.created.append(self)
@@ -210,143 +199,6 @@ def test_create_app_authenticates_control_plane_routes(
assert client.post(path, headers={"Authorization": "Bearer secret-token"}, json={}).status_code != 401
-def test_create_app_creates_scheduler_and_closes_after_shutdown(monkeypatch: pytest.MonkeyPatch) -> None:
- fake_redis = FakeRedis()
- fake_http_client = FakePluginDaemonHttpClient()
- fake_dify_api_http_client = FakePluginDaemonHttpClient()
- FakeRunScheduler.created.clear()
- FakeRedisModule.fake_redis = fake_redis
- monkeypatch.setattr(app_module, "Redis", FakeRedisModule)
- monkeypatch.setattr(app_module, "RunScheduler", FakeRunScheduler)
-
- def fake_create_plugin_daemon_http_client(_settings: ServerSettings) -> FakePluginDaemonHttpClient:
- return fake_http_client
-
- def fake_create_dify_api_inner_http_client(_settings: ServerSettings) -> FakePluginDaemonHttpClient:
- return fake_dify_api_http_client
-
- monkeypatch.setattr(app_module, "create_plugin_daemon_http_client", fake_create_plugin_daemon_http_client)
- monkeypatch.setattr(app_module, "create_dify_api_inner_http_client", fake_create_dify_api_inner_http_client)
-
- settings = ServerSettings(
- redis_url="redis://example.invalid/0",
- redis_prefix="test",
- shutdown_grace_seconds=5,
- run_timeout_seconds=17,
- run_retention_seconds=7,
- run_event_stream_max_length=23,
- stream_text_delta_coalescing_enabled=False,
- stream_text_delta_flush_interval_ms=250,
- stream_text_delta_max_chars=2048,
- plugin_daemon_url="http://plugin-daemon",
- plugin_daemon_api_key="daemon-secret",
- inner_api_url="http://dify-api",
- inner_api_key="inner-secret",
- sandbox_files_base_url="http://api:5001",
- local_sandbox_endpoint="http://shellctl",
- local_sandbox_auth_token="shell-secret",
- agent_stub_api_base_url="https://agent.example.com/agent-stub",
- server_secret_key=_base64url_secret(b"1" * 32),
- outbound_http_connect_timeout=1,
- outbound_http_read_timeout=2,
- outbound_http_write_timeout=3,
- outbound_http_pool_timeout=4,
- outbound_http_max_connections=5,
- outbound_http_max_keepalive_connections=3,
- outbound_http_keepalive_expiry=6,
- )
-
- with TestClient(create_app(settings)):
- assert len(FakeRunScheduler.created) == 1
- scheduler = FakeRunScheduler.created[0]
- assert scheduler.shutdown_grace_seconds == 5
- assert scheduler.run_timeout_seconds == 17
- assert scheduler.stream_text_delta_coalescing_enabled is False
- assert scheduler.stream_text_delta_flush_interval_seconds == 0.25
- assert scheduler.stream_text_delta_max_chars == 2048
- layer_providers = scheduler.layer_providers
- assert isinstance(layer_providers, tuple)
- execution_context_provider = next(
- provider for provider in layer_providers if provider.type_id == "dify.execution_context"
- )
- execution_context_layer = execution_context_provider.create_layer(
- DifyExecutionContextLayerConfig(
- tenant_id="tenant-1",
- user_from="account",
- agent_mode="workflow_run",
- invoke_from="service-api",
- )
- )
- shell_provider = next(provider for provider in layer_providers if provider.type_id == "dify.shell")
- shell_layer = shell_provider.create_layer(DifyShellLayerConfig())
- assert isinstance(execution_context_layer, DifyExecutionContextLayer)
- assert isinstance(shell_layer, DifyShellLayer)
- assert execution_context_layer.daemon_url == "http://plugin-daemon"
- assert execution_context_layer.daemon_api_key == "daemon-secret"
- assert shell_layer.agent_stub_token_factory is not None
- token = shell_layer.agent_stub_token_factory(_execution_context(), session_id="abc12ff")
- token_codec = settings.create_agent_stub_token_codec()
- assert token_codec is not None
- decoded = token_codec.decode_token(token)
- assert decoded.execution_context == _execution_context()
- assert decoded.session_id == "abc12ff"
- knowledge_provider = next(provider for provider in layer_providers if provider.type_id == "dify.knowledge_base")
- knowledge_layer = knowledge_provider.create_layer(
- DifyKnowledgeBaseLayerConfig.model_validate(
- {
- "sets": [
- {
- "id": "support",
- "name": "Support KB",
- "datasets": [{"id": "dataset-1"}],
- "query": {"mode": "generated_query"},
- "retrieval": {"mode": "multiple", "top_k": 2},
- }
- ],
- }
- )
- )
- assert isinstance(knowledge_layer, DifyKnowledgeBaseLayer)
- assert knowledge_layer.inner_api_url == "http://dify-api"
- assert knowledge_layer.inner_api_key == "inner-secret"
- runtime_provider = next(provider for provider in layer_providers if provider.type_id == "dify.runtime")
- runtime_layer = runtime_provider.create_layer(DifyRuntimeLayerConfig(backend_binding_ref="binding-1"))
- assert isinstance(runtime_layer, DifyRuntimeLayer)
- assert isinstance(runtime_layer.backend, LocalExecutionBindingBackend)
- assert shell_layer.agent_stub_api_base_url == "https://agent.example.com/agent-stub"
- http_client = scheduler.plugin_daemon_http_client
- assert http_client is fake_http_client
- assert http_client.is_closed is False
- assert scheduler.dify_api_http_client is fake_dify_api_http_client
- assert scheduler.dify_api_http_client.is_closed is False
- store = scheduler.store
- assert isinstance(store, RedisRunStore)
- assert store.run_retention_seconds == 7
- assert store.run_event_stream_max_length == 23
- assert any(getattr(route, "path", None) == "/agent-stub/connections" for route in create_app(settings).routes)
- assert any(
- getattr(route, "path", None) == "/agent-stub/files/upload-request" for route in create_app(settings).routes
- )
- assert any(
- getattr(route, "path", None) == "/agent-stub/files/download-request"
- for route in create_app(settings).routes
- )
- route_paths = create_app(settings).openapi()["paths"]
- assert {
- "/execution-bindings/files/list",
- "/execution-bindings/files/read",
- "/execution-bindings/files/download",
- }.issubset(route_paths)
- assert "/workspace/files/list" not in route_paths
- assert "/workspace/files/read" not in route_paths
- assert "/workspace/files/upload" not in route_paths
-
- assert FakeRunScheduler.created[0].shutdown_called is True
- assert FakeRunScheduler.created[0].dify_api_http_client.is_closed is True
- assert FakeRunScheduler.created[0].plugin_daemon_http_client.is_closed is True
- assert fake_redis.closed is True
-
-
def test_create_app_wires_authenticated_agent_stub_connection_route(monkeypatch: pytest.MonkeyPatch) -> None:
fake_redis, fake_http_client = _patch_app_lifecycle(monkeypatch)
settings = ServerSettings(
diff --git a/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py b/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py
index 7d48d45fd2e..28f493c45bb 100644
--- a/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py
+++ b/dify-agent/tests/local/dify_agent/server/test_observability_isolation.py
@@ -21,6 +21,8 @@ from pydantic_ai import Agent, Tool
from pydantic_ai.models.test import TestModel
import dify_agent.server.observability as observability
+from pydantic_ai.toolsets import FunctionToolset
+
from dify_agent.runtime.agent_factory import create_agent
from dify_agent.runtime.observability import IsolatedTracerProvider
from dify_agent.server.observability import configure_agent_observability
@@ -156,7 +158,11 @@ def test_agent_pipeline_is_isolated_from_platform_endpoint_and_credentials(
agent_observability = configure_agent_observability(settings)
assert agent_observability is not None
- agent = create_agent(TestModel(custom_output_text="done"), tools=[Tool(_static_tool)])
+ agent = create_agent(
+ TestModel(custom_output_text="done"),
+ toolsets=[FunctionToolset(tools=[Tool(_static_tool)])],
+ capabilities=[],
+ )
assert agent.instrument is False
agent_observability.instrument(agent)
@@ -203,7 +209,9 @@ def test_agent_pipeline_empty_headers_send_no_platform_credentials(
agent_observability = configure_agent_observability(settings)
assert agent_observability is not None
- agent = create_agent(TestModel(custom_output_text="done"), tools=[])
+ agent = create_agent(
+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]
+ )
agent_observability.instrument(agent)
_ = agent.run_sync("business-marker-input")
assert agent_observability.client.force_flush(timeout_millis=10000)
@@ -228,7 +236,9 @@ def test_agent_observability_disabled_creates_no_instance_or_export(
)
assert configure_agent_observability(settings) is None
- agent = create_agent(TestModel(custom_output_text="done"), tools=[])
+ agent = create_agent(
+ TestModel(custom_output_text="done"), toolsets=[FunctionToolset(tools=[])], capabilities=[]
+ )
assert agent.instrument is False
_ = agent.run_sync("business-marker-input")
diff --git a/dify-agent/tests/local/dify_agent/server/test_runs_routes.py b/dify-agent/tests/local/dify_agent/server/test_runs_routes.py
index ce2c6247a7c..c39fed9fddd 100644
--- a/dify-agent/tests/local/dify_agent/server/test_runs_routes.py
+++ b/dify-agent/tests/local/dify_agent/server/test_runs_routes.py
@@ -57,8 +57,8 @@ def test_create_run_accepts_effectively_blank_user_prompt_list() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": ["", " "]}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": ["", " "]}}],
}
},
)
@@ -85,8 +85,8 @@ def test_create_run_returns_running_from_scheduler() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],
}
},
)
@@ -168,12 +168,11 @@ def test_create_run_accepts_valid_full_plugin_graph() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
+ "schema_version": 2,
"layers": [
- {"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}},
+ {"name": "prompt", "config": {"user": "hello"}},
{
"name": "execution-context-renamed",
- "type": "dify.execution_context",
"config": {
"tenant_id": "tenant-1",
"user_from": "account",
@@ -183,8 +182,6 @@ def test_create_run_accepts_valid_full_plugin_graph() -> None:
},
{
"name": DIFY_AGENT_MODEL_LAYER_ID,
- "type": "dify.plugin.llm",
- "deps": {"execution_context": "execution-context-renamed"},
"config": {
"plugin_id": "langgenius/openai",
"model_provider": "openai",
@@ -202,7 +199,7 @@ def test_create_run_accepts_valid_full_plugin_graph() -> None:
assert response.json() == {"run_id": "run-1", "status": "running"}
-def test_create_run_accepts_unknown_layer_exit_signal_request() -> None:
+def test_create_run_rejects_removed_layer_exit_signal_request() -> None:
from fastapi import FastAPI
app = FastAPI()
@@ -215,15 +212,14 @@ def test_create_run_accepts_unknown_layer_exit_signal_request() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],
},
"on_exit": {"layers": {"missing": "delete"}},
},
)
- assert response.status_code == 202
- assert response.json() == {"run_id": "run-1", "status": "running"}
+ assert response.status_code == 422
def test_create_run_accepts_closed_session_snapshot_request() -> None:
@@ -239,8 +235,8 @@ def test_create_run_accepts_closed_session_snapshot_request() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],
},
"session_snapshot": {
"schema_version": 1,
@@ -277,8 +273,8 @@ def test_create_run_returns_503_when_scheduler_is_stopping() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],
}
},
)
@@ -305,8 +301,8 @@ def test_create_run_does_not_map_infrastructure_failure_to_422() -> None:
"/runs",
json={
"composition": {
- "schema_version": 1,
- "layers": [{"name": "prompt", "type": "plain.prompt", "config": {"user": "hello"}}],
+ "schema_version": 2,
+ "layers": [{"name": "prompt", "config": {"user": "hello"}}],
}
},
)
diff --git a/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py b/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py
index 68641aa7a10..33e5da1192f 100644
--- a/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py
+++ b/dify-agent/tests/local/dify_agent/storage/test_redis_run_store.py
@@ -6,8 +6,7 @@ from typing import cast
import pytest
from pydantic import JsonValue
-from agenton.compositor import CompositorSessionSnapshot, LayerSessionSnapshot
-from agenton.layers import LifecycleState
+from dify_agent.protocol.snapshot import SessionSnapshot
from dify_agent.protocol.schemas import (
AgentRunUsage,
RUN_EVENT_ADAPTER,
@@ -189,7 +188,7 @@ def _terminal_event(
run_id=run_id,
data=RunSucceededEventData(
output="done",
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
),
)
if event_type == "run_failed":
@@ -277,7 +276,7 @@ def test_finalize_cancellation_maps_eval_result_and_arguments() -> None:
store.finalize_cancellation(
"run-1",
intent,
- session_snapshot=CompositorSessionSnapshot(layers=[]),
+ session_snapshot=SessionSnapshot(layers={}),
usage=AgentRunUsage(prompt_tokens=13, completion_tokens=8),
)
)
@@ -295,7 +294,7 @@ def test_finalize_cancellation_maps_eval_result_and_arguments() -> None:
assert payload["type"] == "run_cancelled"
assert payload["data"]["reason"] == "workflow_aborted"
assert payload["data"]["message"] == "workflow stopped"
- assert payload["data"]["session_snapshot"] == {"schema_version": 1, "layers": []}
+ assert payload["data"]["session_snapshot"] == {"schema_version": 2, "layers": {}}
assert payload["data"]["usage"]["prompt_tokens"] == 13
assert payload["data"]["usage"]["completion_tokens"] == 8
assert payload["data"]["usage"]["total_tokens"] == 21
@@ -444,15 +443,7 @@ def test_get_events_round_trips_run_succeeded_output_and_session_snapshot() -> N
redis = FakeRedis()
store = RedisRunStore(redis, prefix="test", run_retention_seconds=60) # pyright: ignore[reportArgumentType]
output = cast(JsonValue, {"answer": ["done", 1], "ok": True})
- session_snapshot = CompositorSessionSnapshot(
- layers=[
- LayerSessionSnapshot(
- name="prompt",
- lifecycle_state=LifecycleState.SUSPENDED,
- runtime_state={"resource_id": "abc"},
- )
- ]
- )
+ session_snapshot = SessionSnapshot(layers={"prompt": {"resource_id": "abc"}})
async def scenario() -> tuple[str, RunSucceededEvent]:
record = await store.create_run()
diff --git a/dify-agent/tests/local/dify_agent/test_client_safe_exports.py b/dify-agent/tests/local/dify_agent/test_client_safe_exports.py
index ec4ca696882..4cff38d7f13 100644
--- a/dify-agent/tests/local/dify_agent/test_client_safe_exports.py
+++ b/dify-agent/tests/local/dify_agent/test_client_safe_exports.py
@@ -56,11 +56,6 @@ def test_client_public_exports_work_with_default_dependencies_only(tmp_path: Pat
}
server_only_dependency_names = server_dependency_names - default_dependency_names
- agenton_layers = importlib.import_module("agenton.layers")
- agenton_compositor = importlib.import_module("agenton.compositor")
- agenton_collections = importlib.import_module("agenton_collections")
- plain_layers = importlib.import_module("agenton_collections.layers.plain")
- pydantic_ai_layers = importlib.import_module("agenton_collections.layers.pydantic_ai")
dify_agent = importlib.import_module("dify_agent")
client_module = importlib.import_module("dify_agent.client")
protocol_module = importlib.import_module("dify_agent.protocol")
@@ -70,16 +65,9 @@ def test_client_public_exports_work_with_default_dependencies_only(tmp_path: Pat
shell_module = importlib.import_module("dify_agent.layers.shell")
execution_context_module = importlib.import_module("dify_agent.layers.execution_context")
plugin_module = importlib.import_module("dify_agent.layers.dify_plugin")
- ask_human_module = importlib.import_module("dify_agent.layers.ask_human")
output_module = importlib.import_module("dify_agent.layers.output")
user_prompt_module = importlib.import_module("dify_agent.layers.user_prompt")
- assert agenton_layers.ExitIntent is not None
- assert agenton_layers.LayerConfig is not None
- assert agenton_compositor.CompositorSessionSnapshot is not None
- assert agenton_collections.PromptLayer is plain_layers.PromptLayer
- assert plain_layers.PromptLayerConfig is not None
- assert pydantic_ai_layers.PydanticAIHistoryLayer is not None
assert dify_agent.Client is client_module.Client
assert protocol_module.CreateRunRequest is not None
assert protocol_module.RunComposition is not None
@@ -92,7 +80,6 @@ def test_client_public_exports_work_with_default_dependencies_only(tmp_path: Pat
assert shell_module.DifyShellLayerConfig is not None
assert execution_context_module.DifyExecutionContextLayerConfig is not None
assert plugin_module.DifyPluginLLMLayerConfig is not None
- assert ask_human_module.DifyAskHumanLayerConfig is not None
assert output_module.DifyOutputLayerConfig is not None
assert user_prompt_module.DifyUserPromptLayerConfig is not None
assert user_prompt_module.DifyUserPromptFileConfig is not None
diff --git a/dify-agent/tests/local/dify_agent/test_import_boundaries.py b/dify-agent/tests/local/dify_agent/test_import_boundaries.py
index f23233aa3a2..42438e2adda 100644
--- a/dify-agent/tests/local/dify_agent/test_import_boundaries.py
+++ b/dify-agent/tests/local/dify_agent/test_import_boundaries.py
@@ -105,7 +105,6 @@ def test_protocol_and_dify_plugin_exports_do_not_import_server_only_modules() ->
"anthropic",
"dify_agent.adapters.llm",
"dify_agent.layers.execution_context.layer",
- "dify_agent.layers.ask_human.layer",
"dify_agent.layers.dify_plugin.llm_layer",
"dify_agent.layers.dify_plugin.tools_layer",
"dify_agent.layers.knowledge.client",
@@ -125,7 +124,6 @@ def test_protocol_and_dify_plugin_exports_do_not_import_server_only_modules() ->
imports=[
"dify_agent.protocol",
"dify_agent.layers.execution_context",
- "dify_agent.layers.ask_human",
"dify_agent.layers.dify_plugin",
"dify_agent.layers.knowledge",
"dify_agent.layers.output",
@@ -134,7 +132,6 @@ def test_protocol_and_dify_plugin_exports_do_not_import_server_only_modules() ->
assertions=[
"assert hasattr(dify_agent_protocol, 'CreateRunRequest')",
"assert hasattr(dify_agent_layers_execution_context, 'DifyExecutionContextLayerConfig')",
- "assert hasattr(dify_agent_layers_ask_human, 'DifyAskHumanLayerConfig')",
"assert hasattr(dify_agent_layers_dify_plugin, 'DifyPluginLLMLayerConfig')",
"assert hasattr(dify_agent_layers_knowledge, 'DifyKnowledgeBaseLayerConfig')",
"assert hasattr(dify_agent_layers_output, 'DifyOutputLayerConfig')",
@@ -158,14 +155,12 @@ def test_agent_cli_help_import_is_client_safe() -> None:
"dify_agent.layers._agent_cli_help",
"dify_agent.agent_stub.shell_env",
"dify_agent.layers.shell.layer",
- "dify_agent.runtime.compositor_factory",
],
assertions=[
"assert hasattr(dify_agent_agent_stub_protocol, 'AgentStubConnectRequest')",
"assert hasattr(dify_agent_layers__agent_cli_help, 'render_agent_stub_cli_help')",
"assert hasattr(dify_agent_agent_stub_shell_env, 'build_shell_agent_stub_env')",
- "assert hasattr(dify_agent_layers_shell_layer, 'DifyShellLayer')",
- "assert hasattr(dify_agent_runtime_compositor_factory, 'create_default_layer_providers')",
+ "assert hasattr(dify_agent_layers_shell_layer, 'Capability')",
],
bootstrap=[
"import types",
@@ -279,17 +274,3 @@ def test_server_settings_import_does_not_import_agent_stub_app() -> None:
imports=["dify_agent.server.settings"],
assertions=["assert hasattr(dify_agent_server_settings, 'ServerSettings')"],
)
-
-
-def test_agenton_collection_roots_do_not_eagerly_import_pydantic_ai_implementations() -> None:
- _run_import_check(
- blocked_imports=[
- "agenton_collections.layers.pydantic_ai",
- "agenton_collections.transformers.pydantic_ai",
- ],
- imports=["agenton_collections", "agenton_collections.transformers"],
- assertions=[
- "assert 'PydanticAIBridgeLayer' not in agenton_collections.__all__",
- "assert agenton_collections_transformers.__all__ == []",
- ],
- )
diff --git a/dify-agent/tests/local/examples/test_agenton_examples.py b/dify-agent/tests/local/examples/test_agenton_examples.py
deleted file mode 100644
index 2b0b63a573e..00000000000
--- a/dify-agent/tests/local/examples/test_agenton_examples.py
+++ /dev/null
@@ -1,59 +0,0 @@
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-
-PROJECT_ROOT = Path(__file__).resolve().parents[3]
-
-
-def _run_example(path: str) -> subprocess.CompletedProcess[str]:
- env = os.environ.copy()
- _ = env.pop("OPENAI_API_KEY", None)
- python_path = os.pathsep.join(
- [
- str(PROJECT_ROOT / "src"),
- str(PROJECT_ROOT / "examples" / "agenton"),
- str(PROJECT_ROOT / "examples" / "dify_agent"),
- env.get("PYTHONPATH", ""),
- ]
- )
- env["PYTHONPATH"] = python_path
-
- return subprocess.run(
- [sys.executable, "-m", path],
- cwd=PROJECT_ROOT,
- env=env,
- text=True,
- capture_output=True,
- check=False,
- )
-
-
-def test_agenton_basics_example_smoke() -> None:
- result = _run_example("agenton_examples.basics")
-
- assert result.returncode == 0, result.stderr
- assert "Prompts:" in result.stdout
- assert "User prompts:" in result.stdout
- assert "Tools:" in result.stdout
- assert "Lifecycle: ['create', 'suspend', 'resume', 'delete']" in result.stdout
-
-
-def test_agenton_pydantic_ai_example_smoke() -> None:
- result = _run_example("agenton_examples.pydantic_ai_bridge")
-
- assert result.returncode == 0, result.stderr
- assert "SystemPromptPart(content='Prefer concrete details.'," in result.stdout
- assert "UserPromptPart(content=[\"Use the tools for 'layer composition'.\"]," in result.stdout
- assert "ToolCallPart(tool_name='count_words'" in result.stdout
- assert "ToolCallPart(tool_name='write_tagline'" in result.stdout
- assert "TextPart(content=" in result.stdout
-
-
-def test_agenton_session_snapshot_example_smoke() -> None:
- result = _run_example("agenton_examples.session_snapshot")
-
- assert result.returncode == 0, result.stderr
- assert "Snapshot:" in result.stdout
- assert "Rehydrated external handle: restored:demo-connection" in result.stdout
diff --git a/dify-agent/tests/local/test_packaging.py b/dify-agent/tests/local/test_packaging.py
index ee54057fcc6..ab2d0f96cac 100644
--- a/dify-agent/tests/local/test_packaging.py
+++ b/dify-agent/tests/local/test_packaging.py
@@ -11,7 +11,7 @@ CLIENT_SHARED_DTO_DEPENDENCIES = {
"httpx2>=2.5.0,<3.0.0",
"pydantic>=2.12.5,<2.13",
"pydantic-ai-harness>=0.20.0,<0.21.0",
- "pydantic-ai-slim>=2.30.0,<3.0.0",
+ "pydantic-ai-slim==2.31.0",
"typing-extensions>=4.12.2,<5.0.0",
}
@@ -24,7 +24,7 @@ SERVER_RUNTIME_DEPENDENCIES = {
"jwcrypto>=1.5.6,<2",
"logfire[fastapi,httpx,redis]>=4.37.0,<5.0.0",
"openshell>=0.0.106,<0.1.0",
- "pydantic-ai-slim[anthropic,google,openai]>=2.30.0,<3.0.0",
+ "pydantic-ai-slim[anthropic,google,openai]==2.31.0",
"pydantic-settings>=2.12.0,<3.0.0",
"redis>=7.4.0,<8.0.0",
"uvicorn[standard]==0.46.0",
diff --git a/dify-agent/uv.lock b/dify-agent/uv.lock
index d5b4d754623..060ab961211 100644
--- a/dify-agent/uv.lock
+++ b/dify-agent/uv.lock
@@ -1,5 +1,5 @@
version = 1
-revision = 3
+revision = 5
requires-python = ">=3.13, <4.0"
resolution-markers = [
"python_full_version >= '3.14' and sys_platform == 'win32'",
@@ -590,8 +590,8 @@ requires-dist = [
{ name = "openshell", marker = "extra == 'server'", specifier = ">=0.0.106,<0.1.0" },
{ name = "pydantic", specifier = ">=2.12.5,<2.13" },
{ name = "pydantic-ai-harness", specifier = ">=0.20.0,<0.21.0" },
- { name = "pydantic-ai-slim", specifier = ">=2.30.0,<3.0.0" },
- { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = ">=2.30.0,<3.0.0" },
+ { name = "pydantic-ai-slim", specifier = "==2.31.0" },
+ { name = "pydantic-ai-slim", extras = ["anthropic", "google", "openai"], marker = "extra == 'server'", specifier = "==2.31.0" },
{ name = "pydantic-settings", marker = "extra == 'server'", specifier = ">=2.12.0,<3.0.0" },
{ name = "redis", marker = "extra == 'server'", specifier = ">=7.4.0,<8.0.0" },
{ name = "typing-extensions", specifier = ">=4.12.2,<5.0.0" },