Changelog

Agent Spec 26.1.2

Improvements

• LangGraph adapter timeout and retry improvements

  The LangGraph adapter now applies RetryPolicy.request_timeout and RetryPolicy.max_attempts when converting OpenAI-compatible LLM configurations to ChatOpenAI. It also applies RemoteTool retry policies to HTTP execution by enforcing per-request timeouts and retrying transient HTTP client failures and recoverable HTTP responses.

• Improved HTTPS handling for LangGraph MCP remote transports

  Non-mTLS LangGraph MCP SSE and Streamable HTTP transports now use the standard system trust store for server certificate checks, while mTLS transports continue to use explicit client certificate configuration.

• More reliable tool payload tracing in LangGraph adapter

  The LangGraph adapter now normalizes tool callback inputs before emitting tracing events, preserving structured tool execution payloads more reliably in traced agents and flows.

• Improved OpenAI Agents code generation

  The OpenAI Agents adapter now emits specification-derived string values as Python literals in generated workflow code and validates supported model settings before emission.

• New xAI model provider for OciGenAiConfig

  Introduced a new provider XAI for OciGenAiConfig LLMs.

• Convenience serialization APIs on Components

  Components now expose direct serialization and deserialization helpers: to_yaml(), to_json(), to_dict(), from_yaml(), from_json(), and from_dict(). This provides a shorter API (e.g., agent.to_json()) while preserving compatibility with disaggregated configurations.

  We thank @pullely-samuel for the contribution!

• Disaggregated configurations in LangGraph adapter

  The LangGraph adapter now supports loading disaggregated components during deserialization. Use AgentSpecLoader.load_yaml/json(…, import_only_referenced_components=True) to import referenced components (e.g., LLM configs, tools), optionally modify them, and then pass them back via components_registry when loading the main configuration. This enables keeping sensitive fields (like API keys) out of the main spec while still resolving them at load time.

• Added AGENTS.md file:

  Added AGENTS.md file, a dedicated, open-format guide to help AI coding agents work effectively with the project by providing essential context, build/test commands, code style guidelines, and other key instructions.

  We thank @kanak02rawat for the contribution!

• Tracing in LangGraph adapter flows

  The LangGraph adapter now supports emitting Agent Spec tracing spans and events for Flows. It also adds tracing support for async APIs of LangGraph (e.g. ainvoke, astream). Note that this PR might break existing downstream LangGraph tracing span processors if they run in ab async environment; span processors will need to implement the async APIs (e.g. async def on_event_async) to properly use the async tracing mode.

• Async server tools in LangGraph adapter

  The LangGraph adapter now converts async server-tool callables to StructuredTool(coroutine=...) instead of func=..., so async tools execute correctly when loaded from Agent Spec.

• OCI GenAI model support in LangGraph adapter

  The LangGraph adapter now supports loading/exporting OCI GenAI models. Users can now use models such ss Grok and Meta models available on the OCI GenAI service. Install with pip install pyagentspec[langgraph-full] to access this feature.

• Improved template placeholder rendering in adapters

  Template placeholders in adapter utilities are now rendered by matching placeholders directly in the source template instead of recursively splitting the template text. This keeps unresolved placeholders unchanged and makes the rendering logic easier to follow.

• Component loading defaults

  Agent Spec loaders now expose allowed_components and blocked_components options, allowing users to control which Agent Spec component types can be loaded from configurations. Component type names that resolve to known Component classes use hierarchy matching, like class entries; unresolved type names match only the exact serialized component type.

New features

• URL allow lists for RemoteTool and ApiNode

  Added an optional url_allow_list field to RemoteTool and ApiNode to declare the allowed rendered URL targets when those components use templated URLs.

• Retry policy for components doing remote calls:

  Added retry_policy support to components doing remote calls to enable configuration of retries, backoff, and request timeouts across remote integrations.

  For more information read the guide on using LLM providers.

• Generic LlmConfig with provider-agnostic fields

  LlmConfig is now a concrete class that can be used directly without requiring a dedicated subclass for each LLM provider. New fields model_id, provider, api_provider, api_type, url, and api_key allow describing any LLM connection generically. Existing subclasses (OpenAiConfig, OciGenAiConfig, etc.) continue to work unchanged. All framework adapters support bare LlmConfig instances through string-based dispatch on api_provider.

  We thank @spichen for the contribution!

• Certificate configuration for OpenAI-compatible LLMs

  OpenAiCompatibleConfig now supports optional key_file, cert_file, and ca_file fields for HTTPS and mTLS connections to private endpoints.

  For more information read the how-to guide on using LLM Providers.

• New tool output streaming Event:

  A new ToolExecutionStreamingChunkReceived is introduced to enable surfacing intermediate tool chunks when executing a long-running tool.

• Swarm support in LangGraph adapter:

  The LangGraph adapter now supports the conversion of the Swarm multi-agent pattern.

  To use this, install the optional extra pyagentspec[langgraph].

• CatchExceptionNode:

  Added a new node that executes a subflow and catches exceptions. When an exception is raised, it branches to caught_exception_branch and exposes an additional output string information caught_exception_info.

  For more information and security considerations, read the API Reference.

• Introduced Open Agent Specification Evaluation:

  Open Agent Specification Evaluation (Agent Spec Eval) is an extension of Agent Spec that standardizes how agentic systems are evaluated in a framework-agnostic way.

  The Agent Spec Eval Python SDK is now available as part of pyagentspec. You can access its functionalities through the pyagentspec.evaluation subpackage. It requires the evaluation extra dependency to be installed.

  For more information read the evaluation specification page.

• Added WayFlow adapter to pyagentspec:

  The WayFlow adapter is now available as part of pyagentspec. You can access its functionality through the pyagentspec.adapters.wayflow subpackage. It requires the wayflow extra dependency to be installed.

  For more information read the adapter page.

• Gemini LLM configuration support

  Added GeminiConfig together with GeminiAIStudioAuthConfig and GeminiVertexAIAuthConfig to represent Gemini models in Agent Spec.

  For more information read the API Reference.

• Added Microsoft Agent Framework adapter to pyagentspec:

  The Microsoft Agent Framework adapter is now available as part of pyagentspec. You can access its functionality through the pyagentspec.adapters.agent_framework subpackage. It requires the agent-framework extra dependency to be installed.

• Added OpenAI Agents SDK adapter to pyagentspec:

  The OpenAI Agents adapter is now available as part of pyagentspec. You can access its functionality through the pyagentspec.adapters.openaiagents subpackage. It requires the openai-agents extra dependency to be installed.

  For more information read the adapter page.

• Added Flow Builder to simplify programmatic creation of Agent Spec Flows.

  The Flow Builder is a new chainable API to create and serialize Agent Spec Flows more easily.

  For more information, see the API Reference and the Reference Sheet.

• Datastores

  Added support for datastores in Agent Spec through OracleDatabaseDatastore and PostgresDatabaseDatastore. Datastores enable persistent storage and caching capabilities for agent workflows. InMemoryCollectionDatastore provides a drop-in replacement for development and prototyping.

• Context Summarization Transforms

  Introduced transforms in Agent Spec that allow applying transformations on conversations before being passed to the underlying LLM. We provide MessageSummarizationTransform and ConversationSummarizationTransform for handling long contexts through summarization.

• ToolBox with User Confirmation

  ToolBoxes now have a new flag named requires_confirmation, which can be set to require user/operator approval before running any of the tools in the toolbox. For more information read the API Reference.

Breaking Changes

• HTTPS certificate validation for LangGraph MCP remote transports

  Non-mTLS LangGraph MCP SSE and Streamable HTTP transports now validate the server certificate using the system trust store by default. Connections that previously relied on self-signed, privately issued, expired, or hostname-mismatched certificates may now require updating the certificate setup, trusting the CA in the system store, or switching to the mTLS transport configuration.

• Numeric model settings in OpenAI Agents code generation

  temperature and top_p must now be numeric values, and max_tokens must now be an integer, before the OpenAI Agents adapter emits them into generated workflow code. Configurations that supplied these values as strings should update them to numeric YAML/JSON values.

• Empty titles in properties

  Property titles in Agent Spec must not be empty. This is now enforced by validation in the pyagentspec SDK.

  Migration: If your YAML/JSON configurations have properties without titles, you’ll need to set a non-empty, descriptive title for those properties to pass validation. If you generate Agent Spec configurations via the SDK, your code may still work, but we recommend explicitly setting property titles to ensure forward compatibility.

• MCP stdio transport is blocked by default in Agent Spec loaders

  StdioTransport and its subclasses will no longer load by default through Agent Spec loaders. If a trusted configuration intentionally uses stdio transports, pass blocked_components=[] to the loader, or provide a custom blocked_components value that does not include the stdio transport component class.

Agent Spec 26.1.0

New features

• Added CrewAI adapter to pyagentspec:

  The CrewAI adapter is now available as part of pyagentspec. You can access its functionality through the pyagentspec.adapters.crewai subpackage. It requires the crewai extra dependency to be installed.

  For more information read the API Reference.

• MCP tools support in LangGraph adapter:

  The LangGraph adapter now supports Model Context Protocol (MCP) tools.

  To use this, install the optional extra pyagentspec[langgraph_mcp] and invoke the loaded graph/agent asynchronously via .ainvoke within an async context.

• Added LangGraph adapter to pyagentspec:

  The LangGraph adapter is now available as part of pyagentspec. You can access its functionality through the pyagentspec.adapters.langgraph subpackage. It requires the langgraph extra dependency to be installed.

  For more information read the adapter page.

• Added AutoGen adapter to pyagentspec:

  The AutoGen adapter is now available as part of pyagentspec. You can access its functionality through the pyagentspec.adapters.autogen subpackage. It requires the autogen extra dependency to be installed.

  For more information read the adapter page.

• Sensitive Fields Support:

  New fields have been added to Agent Spec components that may carry sensitive data (e.g. the field api_key on OpenAiCompatibleConfig). To provide this functionality securely, we also introduced the annotation SensitiveField such that the sensitive fields are automatically excluded when exporting a Component to its JSON or yaml configuration.

  For more information read the latest specification.

• OpenAI Responses API Support:

  OpenAiCompatibleConfig and OpenAIModel now support the OpenAI Responses API, which can be configured using the api_type parameter, which accepts values from OpenAIAPIType.

  This enhancement allows recent OpenAI models to better leverage advanced reasoning capabilities, resulting in significant performance improvements in workflows.

  For more information read the API Reference.

• OCI Responses API Support:

  OciGenAiConfig now supports the OCI Responses API, which can be configured using the api_type parameter, which accepts values from OciAPIType.

  This enhancement allows recent models to better leverage advanced reasoning capabilities, resulting in significant performance improvements in workflows.

  For more information read the API Reference.

• ParallelFlowNode and ParallelMapNode

  Added support for parallelization in Agent Spec through ParallelFlowNode, which runs several flows in parallel, and ParallelMapNode, which is a parallel version of the MapNode. For more information, check out the corresponding parallel flows how-to guide and map-reduce how-to guide.

• Tools with User Confirmation

  Tools now have a new flag named requires_confirmation, which can be set to require user/operator approval before running the tool. For more information read the API Reference.

• ToolBoxes

  Toolboxes are now available in the Agent Spec Language Specification and can be passed to Agents. For more information read the API Reference.

• BuiltinTool

  Executor-specific built-in tools are now available in the Agent Spec Language Specification. For more information read the API Reference.

• Structured Generation

  Formally introduced Structured Generation in the Agent Spec Language Specification. Structured Generation is now supported in the LlmNode, as well as the Agent.

• Swarm

  Introduced Swarm in the Agent Spec Language Specification. For more information check out the corresponding swarm how-to guide or read the API Reference.

• AgentSpecialization

  Introduced the concept of agent specialization in the Agent Spec Language Specification, which allows to tailor general-purpose Agents to specific use-cases. For more information read the API Reference.

• ManagerWorkers

  Introduced ManagerWorkers in the Agent Spec Language Specification. For more information check out the corresponding managerworkers how-to guide or read the API Reference.

Improvements

• Extended functionality for data parameter

  Extended the data parameter in RemoteTool and ApiNode from only being a dictionary to any JSON serializable object (including nested objects). Also improved template rendering in the RemoteTool and ApiNode for PyAgentSpec adapters.

• Python 3.14 support

  Introduced support for Python version 3.14.

Breaking Changes

• Sensitive Fields

The below fields have been marked as carrying sensitive information and will be excluded from newly generated configurations automatically. See latest specification for more information on this. This change is implemented retroactively to impact older configurations too.

SSEmTLSTransport	key_file
SSEmTLSTransport	cert_file
SSEmTLSTransport	ca_file
StreamableHTTPmTLSTransport	key_file
StreamableHTTPmTLSTransport	cert_file
StreamableHTTPmTLSTransport	ca_file

These field will now require to be passed explicitly when loading an exported configuration, as in the example below:

AgentSpecDeserializer().from_yaml(
    serialized_component,
    components_registry={
        "<component_id>.key_file": "client.key",
        "<component_id>.cert_file": "client.crt",
        "<component_id>.ca_file": "trustedCA.pem",
    },
)

Agent Spec 25.4.1 — Initial release

Agent Spec is now available: Quickly build portable, framework and language-agnostic agents!

This initial release establishes the foundation of the Agent Spec ecosystem with the first version of the language specification, a Python SDK (PyAgentSpec) for simplified agent development, and a set of adapters that enable running Agent Spec representations on several popular, publicly available agent frameworks.

Explore further:

• Language specification

• How-to Guides

• PyAgentSpec API Reference