Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
"""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
import json
import logging
import time
from collections.abc import AsyncIterable, Callable, Mapping
from dataclasses import dataclass
from typing import Protocol, cast, runtime_checkable
from types import ModuleType
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.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_fs import layer as knowledge_fs_module
from dify_agent.layers.knowledge_fs.history import without_historical_knowledge_evidence
from dify_agent.protocol.schemas import (
AgentRunUsage,
CreateRunRequest,
DIFY_AGENT_MODEL_LAYER_ID,
RunFailureType,
)
from dify_agent.runtime.agent_factory import create_agent, normalize_user_input
from dify_agent.runtime.compaction import build_compaction_capability
from dify_agent.runtime_backend import BindingLostError
from dify_agent.runtime.event_coalescer import (
DEFAULT_TEXT_DELTA_FLUSH_INTERVAL_SECONDS,
DEFAULT_TEXT_DELTA_MAX_CHARS,
coalesce_agent_stream_events,
)
from dify_agent.runtime.event_sink import (
RunEventSink,
RunStreamSealedError,
emit_pydantic_ai_event,
emit_run_failed,
emit_run_started,
emit_run_succeeded,
)
from dify_agent.layers.execution_context.configs import ApplicationTracingContext, DifyExecutionContextLayerConfig
from dify_agent.runtime.observability import AgentObservability, ApplicationAgentObservability
from dify_agent.runtime.user_prompt_validation import EMPTY_USER_PROMPTS_ERROR, has_non_blank_user_prompt
_AGENT_OUTPUT_ADAPTER = TypeAdapter(object)
_MAX_AGENT_STEPS_PER_RUN = 500
DEFAULT_AGENT_RUN_TIMEOUT_SECONDS = 60 * 60
logger = logging.getLogger(__name__)
@runtime_checkable
class _HasAccumulatedUsage(Protocol):
@property
def accumulated_usage(self) -> LLMUsage | None: ...
class AgentRunValidationError(ValueError):
"""Raised when a run request is valid JSON but cannot execute."""
def _run_failed_error_payload(exc: Exception) -> tuple[str, RunFailureType | None, str | None]:
"""Return the public failed-run error text, type, and structured reason."""
message = str(exc) or type(exc).__name__
reason: str | None = None
if isinstance(exc, UsageLimitExceeded):
return message, RunFailureType.AGENT_RUN_LIMIT_EXCEEDED, None
if isinstance(exc, BindingLostError):
return message, None, "binding_lost"
if isinstance(exc, ModelHTTPError):
body = exc.body
if isinstance(body, Mapping):
body_message = body.get("message")
if isinstance(body_message, str) and body_message:
message = body_message
error_type = body.get("error_type")
if isinstance(error_type, str) and error_type:
reason = error_type
if reason is None and exc.status_code == 429:
reason = "InvokeRateLimitError"
if isinstance(exc, DifyKnowledgeBaseClientError):
reason = exc.error_code or "DifyKnowledgeBaseClientError"
return message, None, reason
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):
return event.delta.content_delta
if isinstance(event, PartStartEvent) and isinstance(event.part, TextPart):
return event.part.content
return None
@dataclass(slots=True)
class RunSuccessOutcome:
"""Normalized successful runner output before event emission."""
output: JsonValue | None
session_snapshot: SessionSnapshot
usage: AgentRunUsage | None
class AgentRunRunner:
"""Executes one run and writes only public run events to its sink."""
sink: RunEventSink
request: CreateRunRequest
run_id: str
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
application_observability: ApplicationAgentObservability | None
_terminal_session_snapshot: SessionSnapshot | None
_terminal_usage: AgentRunUsage | None
_knowledge_modules: list[knowledge_fs_module.Capability]
def __init__(
self,
*,
sink: RunEventSink,
request: CreateRunRequest,
run_id: str,
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,
stream_text_delta_flush_interval_seconds: float = DEFAULT_TEXT_DELTA_FLUSH_INTERVAL_SECONDS,
stream_text_delta_max_chars: int = DEFAULT_TEXT_DELTA_MAX_CHARS,
agent_observability: AgentObservability | None = None,
application_observability: ApplicationAgentObservability | None = None,
) -> None:
if stream_text_delta_flush_interval_seconds <= 0:
raise ValueError("stream_text_delta_flush_interval_seconds must be positive")
if stream_text_delta_max_chars <= 0:
raise ValueError("stream_text_delta_max_chars must be positive")
self.sink = sink
self.request = request
self.run_id = run_id
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
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.agent_observability = agent_observability
self.application_observability = application_observability
self._terminal_session_snapshot = None
self._terminal_usage = None
self._knowledge_modules = []
@property
def terminal_session_snapshot(self) -> SessionSnapshot | None:
"""Return the snapshot captured after native capability cleanup."""
return self._terminal_session_snapshot
@property
def terminal_usage(self) -> AgentRunUsage | None:
"""Return usage accumulated before the current run reached any terminal state."""
return self._terminal_usage
async def run(self) -> None:
"""Execute the run and emit the documented event sequence."""
self._terminal_session_snapshot = None
self._terminal_usage = None
execution_context = self._application_execution_context()
started_at_ns = time.time_ns()
if self.is_cancelled():
await self._finalize_application_tracing(execution_context, started_at_ns, error=None, cancelled=True)
return
failure: BaseException | None = None
try:
try:
_ = await emit_run_started(self.sink, run_id=self.run_id)
outcome = await self._run_agent()
except RunStreamSealedError:
# A terminal transition (typically a cancellation accepted by
# another process) sealed the stream first; stop without
# appending a second terminal event.
return
except BaseException as exc:
failure = exc
raise
finally:
await self._finalize_application_tracing(
execution_context,
started_at_ns,
error=failure,
cancelled=isinstance(failure, asyncio.CancelledError) or self.is_cancelled(),
)
except Exception as exc:
if self.is_cancelled():
return
message, error_type, reason = _run_failed_error_payload(exc)
finalization = await emit_run_failed(
self.sink,
run_id=self.run_id,
error=message,
error_type=error_type,
reason=reason,
session_snapshot=self._terminal_session_snapshot,
usage=self._terminal_usage,
)
if finalization.applied:
for module in self._knowledge_modules:
await module.publish_investigation(self.services, status="interrupted")
raise
return
if self.is_cancelled():
return
finalization = await emit_run_succeeded(
self.sink,
run_id=self.run_id,
output=outcome.output,
session_snapshot=outcome.session_snapshot,
usage=outcome.usage,
)
if finalization.applied:
answer = (
outcome.output if isinstance(outcome.output, str) else json.dumps(outcome.output, ensure_ascii=False)
)
for module in self._knowledge_modules:
await module.publish_investigation(self.services, status="completed", answer=answer)
def _application_execution_context(self) -> DifyExecutionContextLayerConfig | None:
"""Resolve valid correlation even if later model/resource setup fails."""
if self.application_observability is None:
return None
try:
layers = {layer.name: layer for layer in self.request.composition.layers}
llm_config = llm_module.Config.model_validate(layers[DIFY_AGENT_MODEL_LAYER_ID].config)
return DifyExecutionContextLayerConfig.model_validate(layers[llm_config.execution_context].config)
except (KeyError, TypeError, ValueError):
return None
async def _finalize_application_tracing(
self,
execution_context: DifyExecutionContextLayerConfig | None,
start_time_ns: int,
*,
error: BaseException | None,
cancelled: bool,
) -> None:
if execution_context is None or execution_context.tracing is None or self.application_observability is None:
return
self.application_observability.record_unstarted_invocation(
execution_context,
start_time_ns=start_time_ns,
end_time_ns=time.time_ns(),
error=error,
cancelled=cancelled,
)
await self.application_observability.finish_invocation(execution_context.tracing)
async def _run_agent(self) -> RunSuccessOutcome:
application_tracing: ApplicationTracingContext | None = None
try:
deps = load_modules(self.request, self.services, self.run_id, registry=self.registry)
modules = create_modules(deps, registry=self.registry)
self._knowledge_modules = [
module for module in modules.values() if isinstance(module, knowledge_fs_module.Capability)
]
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
if message_history:
# Also strip when knowledge was removed from the new Soul.
message_history = without_historical_knowledge_evidence(message_history)
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,
)
execution_context = DifyExecutionContextLayerConfig.model_validate(
deps.layers[llm_config.execution_context]["config"]
)
observability: AgentObservability | None = self.agent_observability
if execution_context.tracing is not None and self.application_observability is not None:
application_tracing = execution_context.tracing
observability = self.application_observability
if observability is not None:
try:
observability.instrument(agent, execution_context=execution_context)
except Exception:
agent.instrument = False
if application_tracing is not None and self.application_observability is not None:
self.application_observability.exporter.mark_incomplete(
(application_tracing.run_id, application_tracing.invocation_id)
)
logger.warning("Agent tracing instrumentation failed; run_id=%s", self.run_id, exc_info=True)
except (KeyError, TypeError, ValueError) as exc:
raise AgentRunValidationError(str(exc)) from exc
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)
)
timeout = asyncio.timeout(self.run_timeout_seconds)
try:
with capture_run_messages() as messages:
finished = False
try:
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),
)
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:
# Native wrap_run scopes have exited, including cancellation cleanup.
self._terminal_session_snapshot = snapshot_modules(deps, registry=self.registry)
if isinstance(model, _HasAccumulatedUsage):
usage = _serialize_agent_usage(model.accumulated_usage)
if usage is not None:
self._terminal_usage = usage
return RunSuccessOutcome(
output=final_output, session_snapshot=self._terminal_session_snapshot, usage=self._terminal_usage
)
def _serialize_agent_output(output: object) -> JsonValue:
"""Convert arbitrary pydantic-ai output into the public JSON-safe payload type."""
return cast(JsonValue, _AGENT_OUTPUT_ADAPTER.dump_python(output, mode="json"))
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"))
return AgentRunUsage(
prompt_tokens=usage.input_tokens,
completion_tokens=usage.output_tokens,
total_tokens=usage.total_tokens,
)
__all__ = ["AgentRunRunner", "AgentRunValidationError"]