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, allowed_components: 'ComponentPolicyInput' | None = None, blocked_components: 'ComponentPolicyInput' | None = None) → ComponentT#

classmethod from_dict(dict_content: ComponentAsDictT, components_registry: 'ComponentsRegistryT' | None, *, plugins: List['ComponentDeserializationPlugin'] | None = None, allowed_components: 'ComponentPolicyInput' | None = None, blocked_components: 'ComponentPolicyInput' | 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.
allowed_components – Optional iterable of component type names or Component classes allowed to be loaded. If omitted, all component types are allowed unless blocked.
blocked_components – Optional iterable of component type names or Component classes blocked from loading. If omitted, this convenience deserialization API does not block any component types by default. Adapter loaders block StdioTransport and its subclasses by default. Resolvable type names and Component classes also 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.

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, allowed_components: 'ComponentPolicyInput' | None = None, blocked_components: 'ComponentPolicyInput' | None = None) → ComponentT#

classmethod from_json(json_content: str, components_registry: 'ComponentsRegistryT' | None, *, plugins: List['ComponentDeserializationPlugin'] | None = None, allowed_components: 'ComponentPolicyInput' | None = None, blocked_components: 'ComponentPolicyInput' | 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.
allowed_components – Optional iterable of component type names or Component classes allowed to be loaded. If omitted, all component types are allowed unless blocked.
blocked_components – Optional iterable of component type names or Component classes blocked from loading. If omitted, this convenience deserialization API does not block any component types by default. Adapter loaders block StdioTransport and its subclasses by default. Resolvable type names and Component classes also 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.

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, allowed_components: 'ComponentPolicyInput' | None = None, blocked_components: 'ComponentPolicyInput' | None = None) → ComponentT#

classmethod from_yaml(yaml_content: str, components_registry: 'ComponentsRegistryT' | None, *, plugins: List['ComponentDeserializationPlugin'] | None = None, allowed_components: 'ComponentPolicyInput' | None = None, blocked_components: 'ComponentPolicyInput' | 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.
allowed_components – Optional iterable of component type names or Component classes allowed to be loaded. If omitted, all component types are allowed unless blocked.
blocked_components – Optional iterable of component type names or Component classes blocked from loading. If omitted, this convenience deserialization API does not block any component types by default. Adapter loaders block StdioTransport and its subclasses by default. Resolvable type names and Component classes also 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.

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

Base Class#

class pyagentspec.component.AbstractableModel#

Bases: BaseModel

Define abstract models that cannot be instantiated.

Example Usage:#

class Component(AbstractableModel, abstract=True):
    pass