Components

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

Component class

class pyagentspec.component.Component(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v26_2_0)

Bases: AbstractableModel

Base class for all components that can be used in Agent Spec.

In Agent Spec, there are components to represent Agents, Flows, LLMs, etc.

Parameters:

• id (str) – A unique identifier for this Component

• name (str) – Name of this Component

• description (str | None) – Optional description of this Component

• metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

• min_agentspec_version (AgentSpecVersionEnum) –

• max_agentspec_version (AgentSpecVersionEnum) –

classmethod build_from_partial_config(partial_config, plugins=None)

Build the component without running any validation.

Parameters:

• partial_config (Dict[str, Any]) – A dictionary containing an incomplete configuration that should be used to build this Component

• plugins (List[ComponentDeserializationPlugin] | None) – The list of ComponentDeserializationPlugin instances needed to build the component

Returns:

The constructed component

Return type:

Component

property component_type: str

Return the name of this Component’s type.

classmethod from_dict(dict_content: ComponentAsDictT, *, plugins: List['ComponentDeserializationPlugin'] | None = None) → ComponentT

classmethod from_dict(dict_content: ComponentAsDictT, components_registry: 'ComponentsRegistryT' | None, *, plugins: List['ComponentDeserializationPlugin'] | None = None) → ComponentT

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.

• plugins – List of plugins to deserialize additional components.

Returns:

The deserialized component typed as cls.

Return type:

ComponentT

Examples

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

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import VllmConfig
>>> 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 = agent.to_dict()

Then deserialize using the convenience API.

>>> deser_agent = Agent.from_dict(agent_config)

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

>>> agent_config, disag_config = agent.to_dict(
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True,
... )
>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> disag_components = AgentSpecDeserializer().from_dict(
...     disag_config,
...     import_only_referenced_components=True
... )
>>> deser_agent = Agent.from_dict(
...     agent_config,
...     components_registry=disag_components
... )

classmethod from_json(json_content: str, *, plugins: List['ComponentDeserializationPlugin'] | None = None) → ComponentT

classmethod from_json(json_content: str, components_registry: 'ComponentsRegistryT' | None, *, plugins: List['ComponentDeserializationPlugin'] | None = None) → ComponentT

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.

• plugins – List of plugins to deserialize additional components.

Returns:

The deserialized component typed as cls.

Return type:

ComponentT

Examples

See examples in the .from_dict method docstring.

classmethod from_yaml(yaml_content: str, *, plugins: List['ComponentDeserializationPlugin'] | None = None) → ComponentT

classmethod from_yaml(yaml_content: str, components_registry: 'ComponentsRegistryT' | None, *, plugins: List['ComponentDeserializationPlugin'] | None = None) → ComponentT

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.

• plugins – List of plugins to deserialize additional components.

Returns:

The deserialized component typed as cls.

Return type:

ComponentT

Examples

See examples in the .from_dict method docstring.

static get_class_from_name(class_name)

Given the class name of a component, return the respective class.

Parameters:

class_name (str) – The name of the component’s class to retrieve

Returns:

The component’s class

Return type:

Component

classmethod get_validation_errors(partial_config, plugins=None)

Return a list of validation errors for this Component.

Parameters:

• partial_config (Dict[str, Any]) – The partial configuration of the Component.

• plugins (List[ComponentDeserializationPlugin] | None) – The list of ComponentDeserializationPlugin instances needed to build the component

Returns:

• The list of validation errors for this Component. If the returned list is empty, the

• component can be constructed without any additional validation.

Return type:

List[PyAgentSpecErrorDetails]

get_versioned_model_fields(agentspec_version)

Returns the dictionary of model fields info.

Parameters:

agentspec_version (AgentSpecVersionEnum) –

Return type:

Dict[str, FieldInfo]

property model_fields_set: set[str]

Returns the set of fields that have been explicitly set on this model instance, except the min_agentspec_version which is manually specified.

classmethod model_json_schema(by_alias=True, ref_template='#/$defs/{model}', schema_generator=<class 'pydantic.json_schema.GenerateJsonSchema'>, mode='validation', only_core_components=False, **kwargs)

Build the json schema for Agent Spec Components.

Note that arguments of the method are ignored.

Parameters:

• by_alias (bool) – Whether to use attribute aliases or not.

• ref_template (str) – The reference template.

• schema_generator (type[pydantic.json_schema.GenerateJsonSchema]) – To override the logic used to generate the JSON schema, as a subclass of GenerateJsonSchema with your desired modifications

• mode (Literal['validation', 'serialization']) – The mode in which to generate the schema.

• only_core_components (bool) – Generate the schema containing only core Agent Spec components as per language specification

• kwargs (Any) –

Returns:

The json schema specification for the chosen Agent Spec Component

Return type:

JsonSchemaValue

serialize_model(info)

Serialize a Pydantic Component.

Is invoked upon a model_dump call.

Parameters:

info (SerializationInfo) –

to_dict(*, plugins: List['ComponentSerializationPlugin'] | None = None) → ComponentAsDictT

to_dict(agentspec_version: AgentSpecVersionEnum | None, *, plugins: List['ComponentSerializationPlugin'] | None = None) → ComponentAsDictT

to_dict(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, plugins: List['ComponentSerializationPlugin'] | None = None) → ComponentAsDictT

to_dict(*, export_disaggregated_components: Literal[False], plugins: List['ComponentSerializationPlugin'] | None = None) → ComponentAsDictT

to_dict(*, export_disaggregated_components: bool, plugins: List['ComponentSerializationPlugin'] | None = None) → 'ComponentAsDictT' | Tuple['ComponentAsDictT', 'DisaggregatedComponentsAsDictT']

to_dict(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: Literal[False], plugins: List['ComponentSerializationPlugin'] | None = None) → ComponentAsDictT

to_dict(*, disaggregated_components: DisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True], plugins: List['ComponentSerializationPlugin'] | None = None) → Tuple['ComponentAsDictT', 'DisaggregatedComponentsAsDictT']

to_dict(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: bool, plugins: List['ComponentSerializationPlugin'] | None = None) → 'ComponentAsDictT' | Tuple['ComponentAsDictT', 'DisaggregatedComponentsAsDictT']

to_dict(agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: bool, *, plugins: List['ComponentSerializationPlugin'] | None = None) → 'ComponentAsDictT' | Tuple['ComponentAsDictT', 'DisaggregatedComponentsAsDictT']

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

Parameters:

• 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.

• plugins – List of plugins to serialize additional components.

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
>>> 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 = agent.to_dict()

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 = agent.to_dict(
...     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 = agent.to_dict(
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True,
... )
>>> list(disag_config["$referenced_components"].keys())
['custom_llm_id']

to_json(*, indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_json(agentspec_version: AgentSpecVersionEnum | None, *, indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_json(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_json(*, export_disaggregated_components: Literal[False], indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_json(*, export_disaggregated_components: bool, indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str | Tuple[str, str]

to_json(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: Literal[False], indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_json(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: Literal[True], indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → Tuple[str, str]

to_json(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: bool, indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str | Tuple[str, str]

to_json(agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: bool, *, indent: int | None = None, plugins: List['ComponentSerializationPlugin'] | None = None) → str | Tuple[str, str]

Serialize this component and its sub-components to JSON.

Parameters:

• 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.

• plugins – List of plugins to serialize additional components.

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(*, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_yaml(agentspec_version: AgentSpecVersionEnum | None = None, *, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_yaml(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_yaml(*, export_disaggregated_components: Literal[False], plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_yaml(*, export_disaggregated_components: bool, plugins: List['ComponentSerializationPlugin'] | None = None) → str | Tuple[str, str]

to_yaml(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: Literal[False], plugins: List['ComponentSerializationPlugin'] | None = None) → str

to_yaml(*, disaggregated_components: DisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True], plugins: List['ComponentSerializationPlugin'] | None = None) → Tuple[str, str]

to_yaml(*, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: bool, plugins: List['ComponentSerializationPlugin'] | None = None) → str | Tuple[str, str]

to_yaml(agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: 'DisaggregatedComponentsConfigT' | None, export_disaggregated_components: bool, *, plugins: List['ComponentSerializationPlugin'] | None = None) → str | Tuple[str, str]

Serialize this component and its sub-components to YAML.

Parameters:

• 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.

• plugins – List of plugins to serialize additional components.

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.

ComponentWithIO class

class pyagentspec.component.ComponentWithIO(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v26_2_0, inputs=None, outputs=None)

Bases: Component

Base class for all components that have input and output schemas.

Parameters:

• id (str) – A unique identifier for this Component

• name (str) – Name of this Component

• description (str | None) – Optional description of this Component

• metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

• min_agentspec_version (AgentSpecVersionEnum) –

• max_agentspec_version (AgentSpecVersionEnum) –

• inputs (List[Property] | None) – List of inputs accepted by this component

• outputs (List[Property] | None) – List of outputs exposed by this component

inputs: List[Property] | None

List of inputs accepted by this component

outputs: List[Property] | None

List of outputs exposed by this component

AgenticComponent class

class pyagentspec.agenticcomponent.AgenticComponent(*, id=<factory>, name, description=None, metadata=<factory>, min_agentspec_version=AgentSpecVersionEnum.v25_4_1, max_agentspec_version=AgentSpecVersionEnum.v26_2_0, inputs=None, outputs=None)

Bases: ComponentWithIO

Represents a component that can be interacted with, asking questions and getting answers from it.

Parameters:

• id (str) – A unique identifier for this Component

• name (str) – Name of this Component

• description (str | None) – Optional description of this Component

• metadata (Dict[str, Any] | None) – Optional, additional metadata related to this Component

• min_agentspec_version (AgentSpecVersionEnum) –

• max_agentspec_version (AgentSpecVersionEnum) –

• inputs (List[Property] | None) – List of inputs accepted by this component

• outputs (List[Property] | None) – List of outputs exposed by this component

inputs: List[Property] | None

List of inputs accepted by this component

outputs: List[Property] | None

List of outputs exposed by this component

Base Class

class pyagentspec.component.AbstractableModel

Bases: BaseModel

Define abstract models that cannot be instantiated.

Example Usage:

class Component(AbstractableModel, abstract=True):
    pass