Agent Spec Adapters#

Using adapters is the recommended way of integrating an agentic framework runtime. Ideally, an adapter should programmatically translate the representation of the Agent Spec components into the equivalent solution, as per each framework’s definition, and return an object that developers can run.

This page presents all APIs and classes related to Agent Spec Adapters.

LangGraph#

class pyagentspec.adapters.langgraph.AgentSpecExporter(plugins=None)#

Bases: AdapterAgnosticAgentSpecExporter

Helper class to convert LangGraph objects into Agent Spec configuration.

Parameters:: plugins (List[ComponentSerializationPlugin] | None) –

property runtime_to_agentspec_converter: RuntimeToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

to_dict(runtime_component: _RuntimeComponentT) → dict[str, Any]#

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

Transform the given LangGraph component into the respective Agent Spec dictionary.

Parameters:

runtime_component – LangGraph component to serialize to an Agent Spec configuration.
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.

Returns:

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

to_json(runtime_component: _RuntimeComponentT) → str#

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given LangGraph component into the respective Agent Spec JSON representation.

Parameters:

runtime_component – LangGraph component to serialize to an Agent Spec configuration.
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.

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.

to_yaml(runtime_component: _RuntimeComponentT) → str#

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given LangGraph component into the respective Agent Spec YAML representation.

Parameters:

runtime_component – LangGraph component to serialize to an Agent Spec configuration.
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.

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.

class pyagentspec.adapters.langgraph.AgentSpecLoader(tool_registry=None, plugins=None, checkpointer=None, config=None)#

Bases: AdapterAgnosticAgentSpecLoader

Helper class to convert Agent Spec configuration into LangGraph objects.

Parameters:

tool_registry (Dict[str, Any] | None) – Optional dictionary to enable converting/loading assistant configurations involving the use of tools. Keys must be the tool names as specified in the serialized configuration, and values are either LangGraph/LCEL tools (e.g., StructuredTool) or plain callables that will be wrapped.
plugins (List[ComponentDeserializationPlugin] | None) – Optional list of Agent Spec deserialization plugins. If omitted, the builtin plugins compatible with the latest supported Agent Spec version are used.
checkpointer (None | bool | BaseCheckpointSaver) – Optional LangGraph checkpointer. If provided, it is wired into created graphs and enables features that require a checkpointer (e.g., client tools).
config (RunnableConfig | None) – Optional RunnableConfig to pass to created runnables/graphs.

property agentspec_to_runtime_converter: AgentSpecToLangGraphConverter#: Instance of runtime converter used to convert runtime components.

load_component(agentspec_component)#

Convert a PyAgentSpec component into a runtime component.

Subclasses may override this method to pass adapter-specific parameters into their converter (e.g., tool registries).

Parameters:: agentspec_component (Component) –
Return type:: StateGraph[Any, Any, Any, StateT] | CompiledStateGraph[Any, Any, Any, StateT] | BaseChatModel | StructuredTool

load_dict(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec JSON into LangGraph components, with support for disaggregated configurations.

Parameters:

serialized_assistant (Dict[str, Any]) – Serialized Agent Spec configuration as a dictionary.
components_registry (Dict[str, StateGraph[Any, Any, Any, StateT] | CompiledStateGraph[Any, Any, Any, StateT] | BaseChatModel | StructuredTool | Any] | None) – Optional registry mapping ids to LangGraph components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to LangGraph components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled LangGraph graph.

Returns:

If import_only_referenced_components is False
CompiledStateGraph – The compiled LangGraph component.
If import_only_referenced_components is True
Dict[str, LangGraphRuntimeComponent] – A dictionary containing the converted referenced components.

Return type:

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_dict, disag_dict = AgentSpecSerializer().to_dict(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.langgraph import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_dict(disag_dict, import_only_referenced_components=True)
>>> langgraph = loader.load_dict(main_dict, components_registry=registry)

Alternatively, you can deserialize the disaggregated components with the pyagentspec deserializer and pass them into the load of the main component:

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deserializer = AgentSpecDeserializer()
>>> referenced_components = deserializer.from_dict(disag_dict, import_only_referenced_components=True)
>>> agentspec_agent = deserializer.from_dict(main_dict, components_registry=referenced_components)
>>> compiled = loader.load_component(agentspec_agent)

load_json(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec JSON into LangGraph components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (Dict[str, StateGraph[Any, Any, Any, StateT] | CompiledStateGraph[Any, Any, Any, StateT] | BaseChatModel | StructuredTool | Any] | None) – Optional registry mapping ids to LangGraph components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to LangGraph components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled LangGraph graph.

Returns:

If import_only_referenced_components is False
CompiledStateGraph – The compiled LangGraph component.
If import_only_referenced_components is True
Dict[str, LangGraphRuntimeComponent] – A dictionary containing the converted referenced components.

Return type:

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_json, disag_json = AgentSpecSerializer().to_json(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.langgraph import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_json(disag_json, import_only_referenced_components=True)
>>> langgraph = loader.load_json(main_json, components_registry=registry)

Alternatively, you can deserialize the disaggregated components with the pyagentspec deserializer and pass them into the load of the main component:

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deserializer = AgentSpecDeserializer()
>>> referenced_components = deserializer.from_json(disag_json, import_only_referenced_components=True)
>>> agentspec_agent = deserializer.from_json(main_json, components_registry=referenced_components)
>>> compiled = loader.load_component(agentspec_agent)

load_yaml(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec YAML into LangGraph components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (Dict[str, StateGraph[Any, Any, Any, StateT] | CompiledStateGraph[Any, Any, Any, StateT] | BaseChatModel | StructuredTool | Any] | None) – Optional registry mapping ids to LangGraph components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to LangGraph components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled LangGraph graph.

Returns:

If import_only_referenced_components is False
CompiledStateGraph – The compiled LangGraph component.
If import_only_referenced_components is True
Dict[str, LangGraphRuntimeComponent] – A dictionary containing the converted referenced components.

Return type:

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_yaml, disag_yaml = AgentSpecSerializer().to_yaml(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.langgraph import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_yaml(disag_yaml, import_only_referenced_components=True)
>>> compiled = loader.load_yaml(main_yaml, components_registry=registry)

Alternatively, you can deserialize the disaggregated components with the pyagentspec deserializer and pass them into the load of the main component:

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deserializer = AgentSpecDeserializer()
>>> referenced_components = deserializer.from_yaml(disag_yaml, import_only_referenced_components=True)
>>> agentspec_agent = deserializer.from_yaml(main_yaml, components_registry=referenced_components)
>>> compiled = loader.load_component(agentspec_agent)

property runtime_to_agentspec_converter: LangGraphToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

CrewAI#

class pyagentspec.adapters.crewai.AgentSpecExporter(plugins=None)#

Bases: AdapterAgnosticAgentSpecExporter

Helper class to convert CrewAI objects to Agent Spec configurations.

Parameters:: plugins (List[ComponentSerializationPlugin] | None) –

property runtime_to_agentspec_converter: RuntimeToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

to_dict(runtime_component: _RuntimeComponentT) → dict[str, Any]#

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

Transform the given CrewAI component into the respective Agent Spec dictionary.

Parameters:

runtime_component – CrewAI component to serialize to an Agent Spec configuration.
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.

Returns:

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

to_json(runtime_component: _RuntimeComponentT) → str#

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given CrewAI component into the respective Agent Spec JSON representation.

Parameters:

runtime_component – CrewAI component to serialize to an Agent Spec configuration.
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.

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.

to_yaml(runtime_component: _RuntimeComponentT) → str#

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given CrewAI component into the respective Agent Spec YAML representation.

Parameters:

runtime_component – CrewAI component to serialize to an Agent Spec configuration.
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.

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.

class pyagentspec.adapters.crewai.AgentSpecLoader(tool_registry=None, plugins=None, *, enable_agentspec_tracing=True)#

Bases: AdapterAgnosticAgentSpecLoader

Helper class to convert Agent Spec configurations to CrewAI objects.

Parameters:

tool_registry (Dict[str, Any] | None) –
plugins (List[Any] | None) –
enable_agentspec_tracing (bool) –

property agentspec_to_runtime_converter: AgentSpecToRuntimeConverter#: Instance of runtime converter used to convert runtime components.

load_dict(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec dictionary into CrewAI components, with support for disaggregated configurations.

Parameters:

serialized_assistant (Dict[str, Any]) – Serialized Agent Spec configuration as a dictionary.
components_registry (Dict[str, Any] | None) – Optional registry mapping ids to CrewAI components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to CrewAI components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled CrewAI graph.

Returns:

If import_only_referenced_components is False
Any – The converted CrewAI component.
If import_only_referenced_components is True
Dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

Any

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_dict, disag_dict = AgentSpecSerializer().to_dict(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.crewai import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_dict(disag_dict, import_only_referenced_components=True)
>>> crewai = loader.load_dict(main_dict, components_registry=registry)

load_json(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec JSON into CrewAI components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (Dict[str, Any] | None) – Optional registry mapping ids to CrewAI components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to CrewAI components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled CrewAI graph.

Returns:

If import_only_referenced_components is False
Any – The converted CrewAI component.
If import_only_referenced_components is True
Dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

Any

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_json, disag_json = AgentSpecSerializer().to_json(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.crewai import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_json(disag_json, import_only_referenced_components=True)
>>> crewai = loader.load_json(main_json, components_registry=registry)

load_yaml(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec YAML into CrewAI components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (Dict[str, Any] | None) – Optional registry mapping ids to CrewAI components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to CrewAI components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled CrewAI graph.

Returns:

If import_only_referenced_components is False
Any – The converted CrewAI component.
If import_only_referenced_components is True
Dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

Any

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_yaml, disag_yaml = AgentSpecSerializer().to_yaml(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.crewai import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_yaml(disag_yaml, import_only_referenced_components=True)
>>> compiled = loader.load_yaml(main_yaml, components_registry=registry)

property runtime_to_agentspec_converter: RuntimeToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

AutoGen#

class pyagentspec.adapters.autogen.AgentSpecExporter(plugins=None)#

Bases: AdapterAgnosticAgentSpecExporter

Helper class to convert AutoGen objects to Agent Spec configurations.

Parameters:: plugins (List[ComponentSerializationPlugin] | None) –

property runtime_to_agentspec_converter: RuntimeToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

to_dict(runtime_component: _RuntimeComponentT) → dict[str, Any]#

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

Transform the given AutoGen component into the respective Agent Spec dictionary.

Parameters:

runtime_component – AutoGen component to serialize to an Agent Spec configuration.
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.

Returns:

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

to_json(runtime_component: _RuntimeComponentT) → str#

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given AutoGen component into the respective Agent Spec JSON representation.

Parameters:

runtime_component – AutoGen component to serialize to an Agent Spec configuration.
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.

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.

to_yaml(runtime_component: _RuntimeComponentT) → str#

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given AutoGen component into the respective Agent Spec YAML representation.

Parameters:

runtime_component – AutoGen component to serialize to an Agent Spec configuration.
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.

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.

class pyagentspec.adapters.autogen.AgentSpecLoader(tool_registry=None, plugins=None)#

Bases: AdapterAgnosticAgentSpecLoader

Helper class to convert Agent Spec configurations to AutoGen objects.

Parameters:

tool_registry (Dict[str, Any] | None) –
plugins (List[ComponentDeserializationPlugin] | None) –

property agentspec_to_runtime_converter: AgentSpecToRuntimeConverter#: Instance of runtime converter used to convert runtime components.

load_dict(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec JSON into AutoGen components, with support for disaggregated configurations.

Parameters:

serialized_assistant (Dict[str, Any]) – Serialized Agent Spec configuration.
components_registry (Dict[str, Any] | None) – Optional registry mapping ids to AutoGen components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to AutoGen components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled AutoGen graph.

Returns:

If import_only_referenced_components is False
AutogenAssistantAgent – The AutoGen component.
If import_only_referenced_components is True
Dict[str, AutogenAssistantAgent] – A dictionary containing the converted referenced components.

Return type:

Any | Dict[str, Any]

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_dict, disag_dict = AgentSpecSerializer().to_dict(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.autogen import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_dict(disag_dict, import_only_referenced_components=True)
>>> autogen = loader.load_dict(main_dict, components_registry=registry)

Alternatively, you can deserialize the disaggregated components with the pyagentspec deserializer and pass them into the load of the main component:

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deserializer = AgentSpecDeserializer()
>>> referenced_components = deserializer.from_dict(disag_dict, import_only_referenced_components=True)
>>> agentspec_agent = deserializer.from_dict(main_dict, components_registry=referenced_components)
>>> autogen_agent = loader.load_component(agentspec_agent)

load_json(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec JSON into AutoGen components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (Dict[str, Any] | None) – Optional registry mapping ids to AutoGen components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to AutoGen components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled AutoGen graph.

Returns:

If import_only_referenced_components is False
Any – The converted AutoGen component.
If import_only_referenced_components is True
Dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

Any | Dict[str, Any]

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_json, disag_json = AgentSpecSerializer().to_json(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.autogen import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_json(disag_json, import_only_referenced_components=True)
>>> autogen = loader.load_json(main_json, components_registry=registry)

Alternatively, you can deserialize the disaggregated components with the pyagentspec deserializer and pass them into the load of the main component:

>>> from pyagentspec.serialization import AgentSpecDeserializer
>>> deserializer = AgentSpecDeserializer()
>>> referenced_components = deserializer.from_json(disag_json, import_only_referenced_components=True)
>>> agentspec_agent = deserializer.from_json(main_json, components_registry=referenced_components)
>>> autogen_agent = loader.load_component(agentspec_agent)

load_yaml(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec YAML into AutoGen components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (Dict[str, Any] | None) – Optional registry mapping ids to AutoGen components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to AutoGen components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled AutoGen graph.

Returns:

If import_only_referenced_components is False
Any – The converted AutoGen component.
If import_only_referenced_components is True
Dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

Any | Dict[str, Any]

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_yaml, disag_yaml = AgentSpecSerializer().to_yaml(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.autogen import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_yaml(disag_yaml, import_only_referenced_components=True)
>>> compiled = loader.load_yaml(main_yaml, components_registry=registry)

property runtime_to_agentspec_converter: RuntimeToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

WayFlow#

class pyagentspec.adapters.wayflow.AgentSpecExporter(plugins=None)#

Bases: object

Helper class to convert WayFlow objects to Agent Spec configurations.

Parameters:: plugins (List[ComponentSerializationPlugin | WayflowSerializationPlugin] | None) –

to_component(runtime_component)#

Transform the given WayFlow component into the respective PyAgentSpec Component.

Parameters:: runtime_component (Component) – WayFlow Component to serialize to a corresponding PyAgentSpec Component.
Return type:: Component

to_json(runtime_component: RuntimeComponent) → str#

to_json(runtime_component: RuntimeComponent, agentspec_version: AgentSpecVersionEnum | None) → str

to_json(runtime_component: RuntimeComponent, *, disaggregated_components: RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_json(runtime_component: RuntimeComponent, *, disaggregated_components: RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_json(runtime_component: RuntimeComponent, *, disaggregated_components: RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_json(runtime_component: RuntimeComponent, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given WayFlow component into the respective Agent Spec JSON representation.

Parameters:

runtime_component – WayFlow component to serialize to an Agent Spec configuration.
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.

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

Basic serialization is done as follows.

>>> from wayflowcore.agent import Agent
>>> from wayflowcore.agentspec import AgentSpecExporter
>>> from wayflowcore.models import VllmModel
>>> from wayflowcore.tools import tool
>>>
>>> llm = VllmModel(
...     model_id="model-id",
...     host_port="VLLM_HOST_PORT",
... )
>>> @tool
... def say_hello_tool() -> str:
...     '''This tool returns "hello"'''
...     return "hello"
...
>>> agent = Agent(
...     name="Simple Agent",
...     llm=llm,
...     tools=[say_hello_tool]
... )
>>> config = AgentSpecExporter().to_json(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.

>>> main_config, disag_config = AgentSpecExporter().to_json(
...     agent,
...     disaggregated_components=[llm],
...     export_disaggregated_components=True
... )

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

>>> main_config, disag_config = AgentSpecExporter().to_json(
...     agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True
... )

to_yaml(runtime_component: RuntimeComponent) → str#

to_yaml(runtime_component: RuntimeComponent, agentspec_version: AgentSpecVersionEnum | None) → str

to_yaml(runtime_component: RuntimeComponent, *, disaggregated_components: RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_yaml(runtime_component: RuntimeComponent, *, disaggregated_components: RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_yaml(runtime_component: RuntimeComponent, *, disaggregated_components: RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_yaml(runtime_component: RuntimeComponent, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given WayFlow component into the respective Agent Spec YAML representation.

Parameters:

runtime_component – WayFlow component to serialize to an Agent Spec configuration.
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.

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

Basic serialization is done as follows.

>>> from wayflowcore.agent import Agent
>>> from wayflowcore.agentspec import AgentSpecExporter
>>> from wayflowcore.models import VllmModel
>>> from wayflowcore.tools import tool
>>>
>>> llm = VllmModel(
...     model_id="model-id",
...     host_port="VLLM_HOST_PORT",
... )
>>> @tool
... def say_hello_tool() -> str:
...     '''This tool returns "hello"'''
...     return "hello"
...
>>> agent = Agent(
...     name="Simple Agent",
...     llm=llm,
...     tools=[say_hello_tool]
... )
>>> config = AgentSpecExporter().to_yaml(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.

>>> main_config, disag_config = AgentSpecExporter().to_yaml(
...     agent,
...     disaggregated_components=[llm],
...     export_disaggregated_components=True
... )

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

>>> main_config, disag_config = AgentSpecExporter().to_yaml(
...     agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True
... )

class pyagentspec.adapters.wayflow.AgentSpecLoader(tool_registry=None, plugins=None)#

Bases: object

Helper class to convert Agent Spec configurations to WayFlow objects.

Parameters:

tool_registry (Dict[str, ServerTool | Callable[[...], Any]] | None) –
plugins (List[WayflowDeserializationPlugin | ComponentDeserializationPlugin] | None) –

load_component(agentspec_component)#

Transform the given PyAgentSpec Component into the respective WayFlow Component

Parameters:: agentspec_component (Component) – PyAgentSpec Component to be converted to a WayFlow Component.
Return type:: Component

load_json(serialized_assistant: str) → RuntimeComponent#

load_json(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None) → RuntimeComponent

load_json(serialized_assistant: str, *, import_only_referenced_components: Literal[False]) → RuntimeComponent

load_json(serialized_assistant: str, *, import_only_referenced_components: Literal[True]) → Dict[str, RuntimeComponent]

load_json(serialized_assistant: str, *, import_only_referenced_components: bool) → RuntimeComponent | Dict[str, RuntimeComponent]

load_json(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None, import_only_referenced_components: Literal[False]) → RuntimeComponent

load_json(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None, import_only_referenced_components: Literal[True]) → Dict[str, RuntimeComponent]

load_json(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None, import_only_referenced_components: bool) → RuntimeComponent | Dict[str, RuntimeComponent]

Transform the given Agent Spec JSON representation into the respective WayFlow Component

Parameters:

serialized_assistant – Serialized Agent Spec configuration to be converted to a WayFlow Component.
components_registry – A dictionary of loaded WayFlow components and values 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 wayflowcore.agent import Agent
>>> from wayflowcore.agentspec import AgentSpecExporter
>>> from wayflowcore.models import VllmModel
>>> from wayflowcore.tools import tool
>>> llm = VllmModel(
...     model_id="model-id",
...     host_port="VLLM_HOST_PORT",
... )
>>> @tool
... def say_hello_tool() -> str:
...     '''This tool returns "hello"'''
...     return "hello"
...
>>> agent = Agent(
...     name="Simple Agent",
...     llm=llm,
...     tools=[say_hello_tool]
... )
>>> config = AgentSpecExporter().to_json(agent)

Then deserialize using the AgentSpecLoader.

>>> from wayflowcore.agentspec import AgentSpecLoader
>>> TOOL_REGISTRY = {"say_hello_tool": say_hello_tool}
>>> loader = AgentSpecLoader(tool_registry=TOOL_REGISTRY)
>>> deser_agent = loader.load_json(config)

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

>>> main_config, disag_config = AgentSpecExporter().to_json(
...     agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True
... )
>>> TOOL_REGISTRY = {"say_hello_tool": say_hello_tool}
>>> loader = AgentSpecLoader(tool_registry=TOOL_REGISTRY)
>>> disag_components = loader.load_json(
...     disag_config, import_only_referenced_components=True
... )
>>> deser_agent = loader.load_json(
...     main_config,
...     components_registry=disag_components
... )

load_yaml(serialized_assistant: str) → RuntimeComponent#

load_yaml(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None) → RuntimeComponent

load_yaml(serialized_assistant: str, *, import_only_referenced_components: Literal[False]) → RuntimeComponent

load_yaml(serialized_assistant: str, *, import_only_referenced_components: Literal[True]) → Dict[str, RuntimeComponent]

load_yaml(serialized_assistant: str, *, import_only_referenced_components: bool) → RuntimeComponent | Dict[str, RuntimeComponent]

load_yaml(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None, import_only_referenced_components: Literal[False]) → RuntimeComponent

load_yaml(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None, import_only_referenced_components: Literal[True]) → Dict[str, RuntimeComponent]

load_yaml(serialized_assistant: str, components_registry: RuntimeComponentsRegistryT | None, import_only_referenced_components: bool) → RuntimeComponent | Dict[str, RuntimeComponent]

Transform the given Agent Spec YAML representation into the respective WayFlow Component

Parameters:

serialized_assistant – Serialized Agent Spec configuration to be converted to a WayFlow Component.
components_registry – A dictionary of loaded WayFlow 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 wayflowcore.agent import Agent
>>> from wayflowcore.agentspec import AgentSpecExporter
>>> from wayflowcore.models import VllmModel
>>> from wayflowcore.tools import tool
>>> llm = VllmModel(
...     model_id="model-id",
...     host_port="VLLM_HOST_PORT",
... )
>>> @tool
... def say_hello_tool() -> str:
...     '''This tool returns "hello"'''
...     return "hello"
...
>>> agent = Agent(
...     name="Simple Agent",
...     llm=llm,
...     tools=[say_hello_tool]
... )
>>> config = AgentSpecExporter().to_yaml(agent)

Then deserialize using the AgentSpecLoader.

>>> from wayflowcore.agentspec import AgentSpecLoader
>>> TOOL_REGISTRY = {"say_hello_tool": say_hello_tool}
>>> loader = AgentSpecLoader(tool_registry=TOOL_REGISTRY)
>>> deser_agent = loader.load_yaml(config)

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

>>> main_config, disag_config = AgentSpecExporter().to_yaml(
...     agent,
...     disaggregated_components=[(llm, "custom_llm_id")],
...     export_disaggregated_components=True
... )
>>> TOOL_REGISTRY = {"say_hello_tool": say_hello_tool}
>>> loader = AgentSpecLoader(tool_registry=TOOL_REGISTRY)
>>> disag_components = loader.load_yaml(
...     disag_config, import_only_referenced_components=True
... )
>>> deser_agent = loader.load_yaml(
...     main_config,
...     components_registry=disag_components
... )

Microsoft Agent Framework#

class pyagentspec.adapters.agent_framework.AgentSpecExporter(plugins=None)#

Bases: AdapterAgnosticAgentSpecExporter

Helper class to convert Microsoft Agent Framework objects to Agent Spec configurations.

Parameters:: plugins (List[ComponentSerializationPlugin] | None) –

property runtime_to_agentspec_converter: RuntimeToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.

to_dict(runtime_component: _RuntimeComponentT) → dict[str, Any]#

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → dict[str, Any]

to_dict(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

to_dict(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → dict[str, Any] | Tuple[str, dict[str, Any]]

Transform the given Microsoft Agent Framework component into the respective Agent Spec dictionary.

Parameters:

runtime_component – Microsoft Agent Framework component to serialize to an Agent Spec configuration.
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.

Returns:

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

to_json(runtime_component: _RuntimeComponentT) → str#

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_json(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_json(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given Microsoft Agent Framework component into the respective Agent Spec JSON representation.

Parameters:

runtime_component – Microsoft Agent Framework component to serialize to an Agent Spec configuration.
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.

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.

to_yaml(runtime_component: _RuntimeComponentT) → str#

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT, export_disaggregated_components: Literal[True]) → Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: Literal[False]) → str

to_yaml(runtime_component: _RuntimeComponentT, *, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

to_yaml(runtime_component: _RuntimeComponentT, agentspec_version: AgentSpecVersionEnum | None, disaggregated_components: _RuntimeDisaggregatedComponentsConfigT | None, export_disaggregated_components: bool) → str | Tuple[str, str]

Transform the given Microsoft Agent Framework component into the respective Agent Spec YAML representation.

Parameters:

runtime_component – Microsoft Agent Framework component to serialize to an Agent Spec configuration.
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.

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.

class pyagentspec.adapters.agent_framework.AgentSpecLoader(tool_registry=None, plugins=None)#

Bases: AdapterAgnosticAgentSpecLoader

Helper class to convert Agent Spec configurations to Microsoft Agent Framework objects.

Parameters:

tool_registry (Dict[str, Any] | None) –
plugins (List[ComponentDeserializationPlugin] | None) –

property agentspec_to_runtime_converter: AgentSpecToAgentFrameworkConverter#: Instance of runtime converter used to convert runtime components.

load_dict(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec dictionary into Microsoft Agent Framework components, with support for disaggregated configurations.

Parameters:

serialized_assistant (dict[str, Any]) – Serialized Agent Spec configuration as a dictionary.
components_registry (dict[str, Any] | None) – Optional registry mapping ids to Microsoft Agent Framework components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to Microsoft Agent Framework components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled Microsoft Agent Framework object.

Returns:

If import_only_referenced_components is False
object – The converted Microsoft Agent Framework component.
If import_only_referenced_components is True
dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

object | dict[str, Any]

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_dict, disag_dict = AgentSpecSerializer().to_dict(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.agent_framework import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_dict(disag_dict, import_only_referenced_components=True)
>>> compiled = loader.load_dict(main_dict, components_registry=registry)

load_json(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec JSON into Microsoft Agent Framework components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (dict[str, Any] | None) – Optional registry mapping ids to Microsoft Agent Framework components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to Microsoft Agent Framework components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled Microsoft Agent Framework object.

Returns:

If import_only_referenced_components is False
object – The converted Microsoft Agent Framework component.
If import_only_referenced_components is True
dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

object | dict[str, Any]

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(id="llm_id", name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_json, disag_json = AgentSpecSerializer().to_json(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.agent_framework import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_json(disag_json, import_only_referenced_components=True)
>>> compiled = loader.load_json(main_json, components_registry=registry)

load_yaml(serialized_assistant, components_registry=None, import_only_referenced_components=False)#

Transform the given Agent Spec YAML into Microsoft Agent Framework components, with support for disaggregated configurations.

Parameters:

serialized_assistant (str) – Serialized Agent Spec configuration.
components_registry (dict[str, Any] | None) – Optional registry mapping ids to Microsoft Agent Framework components/values. The loader will convert these back to Agent Spec components/values internally to resolve references during deserialization.
import_only_referenced_components (bool) – When True, loads only the referenced/disaggregated components and returns a dictionary mapping component id to Microsoft Agent Framework components/values. These can be used as the components_registry when loading the main configuration. When False, loads the main component and returns the compiled Microsoft Agent Framework object.

Returns:

If import_only_referenced_components is False
object – The converted Microsoft Agent Framework component.
If import_only_referenced_components is True
dict[str, Any] – A dictionary containing the converted referenced components.

Return type:

object | dict[str, Any]

Examples

Basic two-phase loading with disaggregation:

>>> from pyagentspec.agent import Agent
>>> from pyagentspec.llms import OllamaConfig
>>> from pyagentspec.serialization import AgentSpecSerializer
>>> agent = Agent(id="agent_id", name="A", system_prompt="You are helpful.", llm_config=OllamaConfig(name="m", model_id="llama3.1", url="http://localhost:11434"))
>>> main_yaml, disag_yaml = AgentSpecSerializer().to_yaml(
...     agent, disaggregated_components=[(agent.llm_config, "llm_id")], export_disaggregated_components=True
... )
>>> from pyagentspec.adapters.agent_framework import AgentSpecLoader
>>> loader = AgentSpecLoader()
>>> registry = loader.load_yaml(disag_yaml, import_only_referenced_components=True)
>>> compiled = loader.load_yaml(main_yaml, components_registry=registry)

property runtime_to_agentspec_converter: AgentFrameworkToAgentSpecConverter#: Instance of runtime converter used to convert runtime components.