Serialization / Deserialization#

This page presents all APIs and classes related to serialization and deserialization in PyAgentSpec.

Serialization#

class pyagentspec.serialization.serializer.AgentSpecSerializer(plugins=None, _allow_partial_model_serialization=False)#

Bases: object

Provides methods to serialize Agent Spec Components.

Parameters:

plugins (List[ComponentSerializationPlugin] | None) –
_allow_partial_model_serialization (bool) –

to_dict(component: Component, *, include_sensitive_fields: bool = False) → Dict[str, Any]#

to_dict(component: Component, agentspec_version: AgentSpecVersionEnum | None, *, include_sensitive_fields: bool = False) → Dict[str, Any]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, include_sensitive_fields: bool = False) → Dict[str, Any]

to_dict(component: Component, *, export_disaggregated_components: Literal[False], include_sensitive_fields: bool = False) → Dict[str, Any]

to_dict(component: Component, *, export_disaggregated_components: bool, include_sensitive_fields: bool = False) → Dict[str, Any] | Tuple[Dict[str, Any], Dict[str, Any]]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[False], include_sensitive_fields: bool = False) → Dict[str, Any]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]], export_disaggregated_components: Literal[True], include_sensitive_fields: bool = False) → Tuple[Dict[str, Any], Dict[str, Any]]

to_dict(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool, include_sensitive_fields: bool = False) → Dict[str, Any] | Tuple[Dict[str, Any], Dict[str, Any]]

to_dict(component: Component, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool, include_sensitive_fields: bool = False) → Dict[str, Any] | Tuple[Dict[str, Any], Dict[str, Any]]

Serialize a component and its sub-components to a dictionary.

Parameters:

component – The component to serialize.
agentspec_version – The Agent Spec version of the component.
disaggregated_components –
Configuration specifying the components/fields to disaggregate upon serialization. Each item can be:
- A Component: to disaggregate the component using its id
- A tuple (Component, str): to disaggregate the component using a custom id.
Note

Components in disaggregated_components are disaggregated even if export_disaggregated_components is False.
export_disaggregated_components – Whether to export the disaggregated components or not. Defaults to False.
include_sensitive_fields –
If False (default), non-empty sensitive fields are exported as $component_ref placeholders. If True, their values are included in the returned serialization. Use this only for trusted local workflows; the returned value may contain secrets or other sensitive data and should not be logged, committed, or shared.

Warning

Enabling this option can expose API keys, credentials, file paths, headers, DSNs, or other sensitive values in the returned data.

Returns:

If export_disaggregated_components is True
ComponentAsDictT – A dictionary containing the serialization of the root component.
DisaggregatedComponentsAsDictT – A dictionary containing the serialization of the disaggregated components.
If export_disaggregated_components is False
ComponentAsDictT – A dictionary containing the serialization of the root component.

Examples

Basic serialization is done as follows.

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import VllmConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> llm = VllmConfig(
...     name="vllm",
...     model_id="model1",
...     url="http://dev.llm.url"
... )
>>> agent = Agent(
...     name="Simple Agent",
...     llm_config=llm,
...     system_prompt="Be helpful"
... )
>>> agent_config = AgentSpecSerializer().to_dict(agent)

To use component disaggregation, specify the component(s) to disaggregate in the disaggregated_components parameter, and ensure that export_disaggregated_components is set to True.

>>> llm = VllmConfig(
...     id="llm_id",
...     name="vllm",
...     model_id="model1",
...     url="http://dev.llm.url"
... )
>>> agent = Agent(name="Simple Agent", llm_config=llm, system_prompt="Be helpful")
>>> agent_config, disag_config = AgentSpecSerializer().to_dict(
...     component=agent,
...     disaggregated_components=[llm],
...     export_disaggregated_components=True,
... )
>>> list(disag_config["$referenced_components"].keys())
['llm_id']

Finally, you can specify custom ids for the disaggregated components.

>>> agent_config, disag_config = AgentSpecSerializer().to_dict(
...     component=agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True,
... )
>>> list(disag_config["$referenced_components"].keys())
['custom_llm_id']

to_json(component: Component, *, indent: int | None = None, include_sensitive_fields: bool = False) → str#

to_json(component: Component, agentspec_version: AgentSpecVersionEnum | None, *, indent: int | None = None, include_sensitive_fields: bool = False) → str

to_json(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, indent: int | None = None, include_sensitive_fields: bool = False) → str

to_json(component: Component, *, export_disaggregated_components: Literal[False], indent: int | None = None, include_sensitive_fields: bool = False) → str

to_json(component: Component, *, export_disaggregated_components: bool, indent: int | None = None, include_sensitive_fields: bool = False) → str | Tuple[str, str]

to_json(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[False], indent: int | None = None, include_sensitive_fields: bool = False) → str

to_json(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[True], indent: int | None = None, include_sensitive_fields: bool = False) → Tuple[str, str]

to_json(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool, indent: int | None = None, include_sensitive_fields: bool = False) → str | Tuple[str, str]

to_json(component: Component, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool, *, indent: int | None = None, include_sensitive_fields: bool = False) → str | Tuple[str, str]

Serialize a component and its sub-components to JSON.

Parameters:

component – The component to serialize.
agentspec_version – The Agent Spec version of the component.
disaggregated_components –
Configuration specifying the components/fields to disaggregate upon serialization. Each item can be:
- A Component: to disaggregate the component using its id
- A tuple (Component, str): to disaggregate the component using a custom id.
Note

Components in disaggregated_components are disaggregated even if export_disaggregated_components is False.
export_disaggregated_components – Whether to export the disaggregated components or not. Defaults to False.
indent – The number of spaces to use for the JSON indentation.
include_sensitive_fields –
If False (default), non-empty sensitive fields are exported as $component_ref placeholders. If True, their values are included in the returned serialization. Use this only for trusted local workflows; the returned value may contain secrets or other sensitive data and should not be logged, committed, or shared.

Warning

Enabling this option can expose API keys, credentials, file paths, headers, DSNs, or other sensitive values in the returned data.

Returns:

If export_disaggregated_components is True
str – The JSON serialization of the root component.
str – The JSON serialization of the disaggregated components.
If export_disaggregated_components is False
str – The JSON serialization of the root component.

Examples

See examples in the .to_dict method docstring.

to_yaml(component: Component, *, include_sensitive_fields: bool = False) → str#

to_yaml(component: Component, agentspec_version: AgentSpecVersionEnum | None = None, *, include_sensitive_fields: bool = False) → str

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, include_sensitive_fields: bool = False) → str

to_yaml(component: Component, *, export_disaggregated_components: Literal[False], include_sensitive_fields: bool = False) → str

to_yaml(component: Component, *, export_disaggregated_components: bool, include_sensitive_fields: bool = False) → str | Tuple[str, str]

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: Literal[False], include_sensitive_fields: bool = False) → str

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]], export_disaggregated_components: Literal[True], include_sensitive_fields: bool = False) → Tuple[str, str]

to_yaml(component: Component, *, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool, include_sensitive_fields: bool = False) → str | Tuple[str, str]

to_yaml(component: Component, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: Sequence[Component | Tuple[Component, str] | Tuple[Component, str, str]] | None, export_disaggregated_components: bool, include_sensitive_fields: bool = False) → str | Tuple[str, str]

Serialize a component and its sub-components to YAML.

Parameters:

component – The component to serialize.
agentspec_version – The Agent Spec version of the component
disaggregated_components –
Configuration specifying the components/fields to disaggregate upon serialization. Each item can be:
- A Component: to disaggregate the component using its id
- A tuple (Component, str): to disaggregate the component using a custom id.
Note

Components in disaggregated_components are disaggregated even if export_disaggregated_components is False.
export_disaggregated_components – Whether to export the disaggregated components or not. Defaults to False.
include_sensitive_fields –
If False (default), non-empty sensitive fields are exported as $component_ref placeholders. If True, their values are included in the returned serialization. Use this only for trusted local workflows; the returned value may contain secrets or other sensitive data and should not be logged, committed, or shared.

Warning

Enabling this option can expose API keys, credentials, file paths, headers, DSNs, or other sensitive values in the returned data.

Returns:

If export_disaggregated_components is True
str – The YAML serialization of the root component.
str – The YAML serialization of the disaggregated components.
If export_disaggregated_components is False
str – The YAML serialization of the root component.

Examples

See examples in the .to_dict method docstring.

Deserialization#

class pyagentspec.serialization.deserializer.AgentSpecDeserializer(plugins=None, allowed_components=None, blocked_components=None)#

Bases: object

Provides methods to deserialize Agent Spec Components.

allowed_components and blocked_components can be used to constrain which Agent Spec component types load. Resolvable type names and Component classes match subclasses; unresolved type names match only the exact serialized component type. When allow and block entries both match, the closest match in the component class hierarchy wins; block entries win same-distance ties.

This low-level deserializer does not block any component types by default. Adapter loaders block StdioTransport and its subclasses by default.

Parameters:

plugins (List[ComponentDeserializationPlugin] | None) –
allowed_components (str | Type[Component] | Iterable[str | Type[Component]] | None) –
blocked_components (str | Type[Component] | Iterable[str | Type[Component]] | None) –

from_dict(dict_content: Dict[str, Any]) → Component#

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None) → Component

from_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: Literal[False]) → Component

from_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: Literal[True]) → dict[str, pyagentspec.component.Component]

from_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: bool) → Component | dict[str, pyagentspec.component.Component]

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[False]) → Component

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[True]) → dict[str, pyagentspec.component.Component]

from_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: bool) → Component | dict[str, pyagentspec.component.Component]

Load a component and its sub-components from dictionary.

Parameters:

dict_content – The loaded serialized component representation as a dictionary.
components_registry – A dictionary of loaded components to use when deserializing the main component.
import_only_referenced_components – When True, loads the referenced/disaggregated components into a dictionary to be used as the components_registry when deserializing the main component. Otherwise, loads the main component. Defaults to False

Returns:

If import_only_referenced_components is False
Component – The deserialized component.
If import_only_referenced_components is False
Dict[str, Component] – A dictionary containing the loaded referenced components.

Examples

Basic deserialization is done as follows. First, serialize a component (here an Agent).

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import VllmConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> llm = VllmConfig(
...     name="vllm",
...     model_id="model1",
...     url="http://dev.llm.url"
... )
>>> agent = Agent(
...     name="Simple Agent",
...     llm_config=llm,
...     system_prompt="Be helpful"
... )
>>> agent_config = AgentSpecSerializer().to_dict(agent)

Then deserialize using the AgentSpecDeserializer.

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deser_agent = AgentSpecDeserializer().from_dict(agent_config)

When using disaggregated components, the deserialization must be done in several phases, as follows.

>>> agent_config, disag_config = AgentSpecSerializer().to_dict(
...     component=agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True,
... )
>>> disag_components = AgentSpecDeserializer().from_dict(
...     disag_config,
...     import_only_referenced_components=True
... )
>>> deser_agent = AgentSpecDeserializer().from_dict(
...     agent_config,
...     components_registry=disag_components
... )

from_json(json_content: str) → Component#

from_json(json_content: str, components_registry: Mapping[str, Component | Any] | None) → Component

from_json(json_content: str, *, import_only_referenced_components: Literal[False]) → Component

from_json(json_content: str, *, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_json(json_content: str, *, import_only_referenced_components: bool) → Component | Dict[str, Component]

from_json(json_content: str, components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[False]) → Component

from_json(json_content: str, components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_json(json_content: str, components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: bool) → Component | Dict[str, Component]

Load a component and its sub-components from JSON.

Parameters:

json_content – The JSON content to use to deserialize the component.
components_registry – A dictionary of loaded components to use when deserializing the main component.
import_only_referenced_components – When True, loads the referenced/disaggregated components into a dictionary to be used as the components_registry when deserializing the main component. Otherwise, loads the main component. Defaults to False

Returns:

If import_only_referenced_components is False
Component – The deserialized component.
If import_only_referenced_components is False
Dict[str, Component] – A dictionary containing the loaded referenced components.

Examples

See examples in the .from_dict method docstring.

from_partial_dict(dict_content: Dict[str, Any]) → tuple[pyagentspec.component.Component, list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]#
from_partial_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None) → tuple[pyagentspec.component.Component, list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]
from_partial_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: Literal[False]) → tuple[pyagentspec.component.Component, list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]
from_partial_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: Literal[True]) → tuple[dict[str, pyagentspec.component.Component], list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]
from_partial_dict(dict_content: Dict[str, Any], *, import_only_referenced_components: bool) → tuple[pyagentspec.component.Component | dict[str, pyagentspec.component.Component], list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]
from_partial_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[False]) → tuple[pyagentspec.component.Component, list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]
from_partial_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[True]) → tuple[dict[str, pyagentspec.component.Component], list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]
from_partial_dict(dict_content: Dict[str, Any], components_registry: Mapping[str, Component | Any] | None = None, import_only_referenced_components: bool = False) → tuple[pyagentspec.component.Component | dict[str, pyagentspec.component.Component], list[pyagentspec.validation_helpers.PyAgentSpecErrorDetails]]

from_yaml(yaml_content: str) → Component#

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Any] | None) → Component

from_yaml(yaml_content: str, *, import_only_referenced_components: Literal[False]) → Component

from_yaml(yaml_content: str, *, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_yaml(yaml_content: str, *, import_only_referenced_components: bool) → Component | Dict[str, Component]

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[False]) → Component

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: Literal[True]) → Dict[str, Component]

from_yaml(yaml_content: str, components_registry: Mapping[str, Component | Any] | None, import_only_referenced_components: bool) → Component | Dict[str, Component]

Load a component and its sub-components from YAML.

Parameters:

yaml_content – The YAML content to use to deserialize the component.
components_registry – A dictionary of loaded components to use when deserializing the main component.
import_only_referenced_components – When True, loads the referenced/disaggregated components into a dictionary to be used as the components_registry when deserializing the main component. Otherwise, loads the main component. Defaults to False

Returns:

If import_only_referenced_components is False
Component – The deserialized component.
If import_only_referenced_components is False
Dict[str, Component] – A dictionary containing the loaded referenced components.

Examples

See examples in the .from_dict method docstring.

Serialization plugins#

class pyagentspec.serialization.serializationcontext.SerializationContext#

Bases: object

Interface for the serialization of Components.

agentspec_version: AgentSpecVersionEnum#

abstract dump_field(value: bool, info: FieldInfoTypeT | None) → bool#
abstract dump_field(value: int, info: FieldInfoTypeT | None) → int
abstract dump_field(value: float, info: FieldInfoTypeT | None) → float
abstract dump_field(value: str, info: FieldInfoTypeT | None) → str
abstract dump_field(value: List[T], info: FieldInfoTypeT | None) → List[Any]
abstract dump_field(value: Dict[str, T], info: FieldInfoTypeT | None) → Dict[str, Any]
abstract dump_field(value: BaseModel, info: FieldInfoTypeT | None) → Dict[str, Any]: Dump a component field based on its value and optional info.

should_redact_field(field_info)#

Return True if the field should be redacted; False when opt-in bypass is active.

Parameters:: field_info (FieldInfo) –
Return type:: bool

class pyagentspec.serialization.serializationplugin.ComponentSerializationPlugin#

Bases: ABC

Base class for Component serialization plugins.

abstract property plugin_name: str#: Return the plugin name.

abstract property plugin_version: str#: Return the plugin version.

abstract serialize(component, serialization_context)#

Serialize a component that the plugin should support.

Parameters:

component (Component) –
serialization_context (SerializationContext) –

Return type:

Dict[str, Any]

abstract supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

class pyagentspec.serialization.pydanticserializationplugin.PydanticComponentSerializationPlugin(component_types_and_models, _allow_partial_model_serialization=False)#

Bases: ComponentSerializationPlugin

Serialization plugin for Pydantic Components.

Parameters:

component_types_and_models (Mapping[str, Type[BaseModel]]) –
_allow_partial_model_serialization (bool) –

property plugin_name: str#: Return the plugin name.

property plugin_version: str#: Return the plugin version.

serialize(component, serialization_context)#

Serialize a Pydantic component.

Parameters:

component (Component) –
serialization_context (SerializationContext) –

Return type:

Dict[str, Any]

supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

Deserialization plugins#

class pyagentspec.serialization.deserializationcontext.DeserializationContext#

Bases: ABC

Interface for the deserialization of Components.

abstract get_component_type(content)#

Get the type of component from the dedicated special field.

Parameters:: content (Dict[str, Any]) –
Return type:: str

abstract load_config_dict(content, components_registry)#

Load an Agent Spec configuration in dictionary form.

Parameters:

content (Dict[str, Any]) –
components_registry (Mapping[str, Component | Any] | None) –

Return type:

Tuple[Component, List[PyAgentSpecErrorDetails]]

abstract load_field(content, annotation)#

Load a field based on its serialized field content and annotated type.

Parameters:

content (Dict[str, Any]) –
annotation (type | None) –

Return type:

Any

class pyagentspec.serialization.deserializationplugin.ComponentDeserializationPlugin#

Bases: ABC

Base class for Component deserialization plugins.

abstract deserialize(serialized_component, deserialization_context)#

Deserialize a serialized component that the plugin should support.

Parameters:

serialized_component (Dict[str, Any]) –
deserialization_context (DeserializationContext) –

Return type:

Component

abstract property plugin_name: str#: Return the plugin name.

abstract property plugin_version: str#: Return the plugin version.

abstract supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

class pyagentspec.serialization.pydanticdeserializationplugin.PydanticComponentDeserializationPlugin(component_types_and_models)#

Bases: ComponentDeserializationPlugin

Deserialization plugin for Pydantic Components.

Parameters:: component_types_and_models (Mapping[str, Type[BaseModel]]) –

deserialize(serialized_component, deserialization_context)#

Deserialize a serialized Pydantic model.

Parameters:

serialized_component (Dict[str, Any]) –
deserialization_context (DeserializationContext) –

Return type:

Component

property plugin_name: str#: Return the plugin name.

property plugin_version: str#: Return the plugin version.

supported_component_types()#

Indicate what component types the plugin supports.

Return type:: List[str]

Validation#

class pyagentspec.validation_helpers.PyAgentSpecErrorDetails(*, type, msg, loc=<factory>)#

Bases: BaseModel

Describe a validation error for an Agent Spec Component.

Parameters:

type (str) –
msg (str) –
loc (Tuple[str | int, ...]) –

loc: Tuple[str | int, ...]#

msg: str#

type: str#