Agent Spec API

Declarative agent definitions in YAML or JSON. See Agent Spec (YAML/JSON) for the conceptual overview.

DeepAgentSpec

pydantic_deep.spec.DeepAgentSpec

Bases: BaseModel

Declarative agent specification - mirrors create_deep_agent() params.

All fields have the same defaults as create_deep_agent(). Only serializable parameters are included (callbacks and Python objects like backend, tools, toolsets must be passed as overrides).

DeepAgent

pydantic_deep.spec.DeepAgent

Factory for creating deep agents from declarative specs.

Provides class methods to load agent configurations from YAML/JSON files or dicts, and save configurations to files.

from_file(path, **overrides) classmethod

Create an agent from a YAML or JSON spec file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to YAML (.yaml/.yml) or JSON (.json) file.	required
**overrides	Any	Override spec values (e.g., model="anthropic:claude-opus-4-6"). Non-serializable params like backend, tools, on_cost_update can only be passed here.	{}

Returns:

Type	Description
tuple[Any, DeepAgentDeps]	Tuple of (agent, deps) ready for agent.run().

Example

Python

agent, deps = DeepAgent.from_file("agent.yaml")
result = await agent.run("Hello", deps=deps)

from_spec(data, **overrides) classmethod

Create an agent from a dict specification.

Parameters:

Name	Type	Description	Default
data	dict[str, Any]	Dict with create_deep_agent() parameter names as keys.	required
**overrides	Any	Override spec values. Takes precedence over data.	{}

Returns:

Type	Description
tuple[Any, DeepAgentDeps]	Tuple of (agent, deps) ready for agent.run().

Example

Python

agent, deps = DeepAgent.from_spec({
    "model": "anthropic:claude-opus-4-6",
    "include_todo": True,
    "include_memory": True,
})

to_file(path, **params) classmethod

Save agent parameters as a YAML or JSON spec file.

Only serializable parameters are saved. Non-serializable params (callbacks, Python objects) are silently excluded.

Parameters:

Name	Type	Description	Default
path	str | Path	Output path. Extension determines format (.yaml/.yml or .json).	required
**params	Any	create_deep_agent() parameters to save.	{}

Example

Python

DeepAgent.to_file(
    "agent.yaml",
    model="anthropic:claude-opus-4-6",
    include_todo=True,
    include_memory=True,
    memory_dir=".pydantic-deep",
)