dify/dify-agent/docs/agenton/api/README.md

Agenton API reference

This page summarizes the public Agenton API. Import paths are shown for the symbols commonly used by layer authors and compositor callers.

Layers: agenton.layers

Layer[DepsT, PromptT, UserPromptT, ToolT, ConfigT, RuntimeStateT, RuntimeHandlesT]

Framework-neutral base class for prompt/tool layers.

Class attributes:

• type_id: str | None: registry id for config-backed plugin layers.
• config_type: type[BaseModel]: Pydantic schema for serialized layer config.
• runtime_state_type: type[BaseModel]: Pydantic schema for snapshot-safe per-session state.
• runtime_handles_type: type[BaseModel]: Pydantic schema for live runtime handles; use arbitrary_types_allowed=True for client/process objects.
• deps_type: type[LayerDeps]: inferred from the layer generic base or declared explicitly.

Construction and dependency APIs:

• from_config(config: ConfigT) -> Self: create a layer from schema-validated config. The default implementation raises TypeError.
• dependency_names() -> frozenset[str]: dependency fields declared by deps_type.
• bind_deps(deps: Mapping[str, Layer | None]) -> None: bind graph dependencies.
• new_control(state=LifecycleState.NEW, runtime_state=None) -> LayerControl: create a schema-validated per-session control.

Lifecycle hooks:

• on_context_create(control)
• on_context_resume(control)
• on_context_suspend(control)
• on_context_delete(control)
• enter(control) / lifecycle_enter(control): async context manager entry surface. Override enter() only when a layer needs to wrap extra resources.

Prompt/tool authoring surfaces:

• prefix_prompts -> Sequence[PromptT]
• suffix_prompts -> Sequence[PromptT]
• user_prompts -> Sequence[UserPromptT]
• tools -> Sequence[ToolT]

Aggregation adapters implemented by typed layer families:

• wrap_prompt(prompt: PromptT) -> object
• wrap_user_prompt(prompt: UserPromptT) -> object
• wrap_tool(tool: ToolT) -> object

LayerControl[RuntimeStateT, RuntimeHandlesT]

Per-layer, per-session lifecycle control.

Fields:

• state: LifecycleState
• exit_intent: ExitIntent
• runtime_state: RuntimeStateT
• runtime_handles: RuntimeHandlesT

Methods:

• suspend_on_exit() -> None
• delete_on_exit() -> None

runtime_state is serialized in session snapshots. runtime_handles is never serialized and should be rehydrated from runtime state in resume hooks.

Schema defaults and lifecycle enums

• EmptyLayerConfig
• EmptyRuntimeState
• EmptyRuntimeHandles
• LifecycleState: NEW, ACTIVE, SUSPENDED, CLOSED
• ExitIntent: DELETE, SUSPEND

Typed layer families: agenton.layers.types

• PlainLayer[DepsT, ConfigT, RuntimeStateT, RuntimeHandlesT]
• PydanticAILayer[DepsT, AgentDepsT, ConfigT, RuntimeStateT, RuntimeHandlesT]

Tagged aggregate item types:

• PlainPromptType, PlainUserPromptType, PlainToolType
• PydanticAIPromptType, PydanticAIUserPromptType, PydanticAIToolType
• AllPromptTypes, AllUserPromptTypes, AllToolTypes

Compositor: agenton.compositor

Config models

• LayerNodeConfig: name, type, config, deps, metadata
• CompositorConfig: schema_version, layers

Config nodes are pure serializable graph input. Use live instances for Python objects and callables.

Registry

LayerRegistry manually registers config-backed layer classes.

• register_layer(layer_type, type_id=None) -> None
• resolve(type_id) -> LayerDescriptor
• descriptors() -> Mapping[str, LayerDescriptor]

LayerDescriptor exposes type_id, layer_type, config_type, runtime_state_type, and runtime_handles_type.

Builder

CompositorBuilder(registry) mixes config-backed nodes and live instances.

• add_config(config) -> Self
• add_config_layer(name, type, config=None, deps=None) -> Self
• add_instance(name, layer, deps=None) -> Self
• build(prompt_transformer=None, user_prompt_transformer=None, tool_transformer=None) -> Compositor

Compositor

Compositor[PromptT, ToolT, LayerPromptT, LayerToolT, UserPromptT, LayerUserPromptT] owns the ordered layer graph.

Construction:

• Compositor(layers=..., deps_name_mapping=..., ...)
• Compositor.from_config(conf, registry=..., ...)

Aggregation properties:

• prompts -> list[PromptT]: prefix prompts in layer order, suffix prompts in reverse layer order, then optional prompt_transformer.
• user_prompts -> list[UserPromptT]: user prompts in layer order, then optional user_prompt_transformer.
• tools -> list[ToolT]: tools in layer order, then optional tool_transformer.

Session APIs:

• new_session() -> CompositorSession
• enter(session=None) -> AsyncIterator[CompositorSession]
• snapshot_session(session) -> CompositorSessionSnapshot
• session_from_snapshot(snapshot) -> CompositorSession

Sessions and snapshots

CompositorSession owns ordered layer controls.

• suspend_on_exit() -> None
• delete_on_exit() -> None
• layer(name) -> LayerControl

Snapshot models:

• LayerSessionSnapshot: name, state, runtime_state
• CompositorSessionSnapshot: schema_version, layers

Snapshots reject active sessions and exclude runtime_handles and exit_intent.

Collection layers and transformers

Plain layers: agenton_collections.layers.plain

• PromptLayer: config-backed layer with PromptLayerConfig(prefix, user, suffix) and type_id = "plain.prompt".
• ObjectLayer: instance-only layer for Python objects.
• ToolsLayer: instance-only layer for callables.
• DynamicToolsLayer: instance-only layer for object-bound callables.

Pydantic AI bridge

agenton_collections.layers.pydantic_ai.PydanticAIBridgeLayer exposes pydantic-ai system prompts, user prompts, and tools while depending on an ObjectLayer for RunContext.deps.

agenton_collections.transformers.PYDANTIC_AI_TRANSFORMERS provides:

• prompt_transformer: maps compositor.prompts to pydantic-ai system prompt functions.
• user_prompt_transformer: maps compositor.user_prompts to pydantic-ai UserContent.
• tool_transformer: maps compositor.tools to pydantic-ai tools.