Changelog#

WayFlow 26.1.2#

New features#

Configurable retry policies for remote components

Added the RetryPolicy object to configure retries, backoff, and request timeouts for components doing remote calls.

For usage details, see the new retry configuration guide.
Custom TLS certificates for OpenAI-compatible models:

OpenAICompatibleModel and OpenAICompatibleEmbeddingModel now support optional key_file, cert_file and ca_file parameters for custom CAs and mutual TLS.

For more information read how to configure custom TLS certificates for OpenAI-compatible endpoints.
OAuth support for MCP Clients:

MCP Clients now support OAuth-based authorization.

For more information read the API Reference and the guide on how to connect assistants to MCP servers.
Message Summarization Transforms and Datastores can be converted between Agent Spec and Wayflow

Added support for converting MessageSummarizationTransform and ConversationSummarizationTransform between Agent Spec and Wayflow. Similarly for Datastores (OracleDatabaseDatastore, PostgreSQLDatabaseDatastore). You can now declare your agents with summarization transforms and summary caching in Agent Spec and run them in WayFlow.
Gemini models (Vertex AI + AI Studio):

Added GeminiModel to run Gemini models via Google Vertex AI and Google AI Studio. For more information read the API Reference on LLM models and the guide on how to use LLMs from different providers.
Logprob support in `LlmGenerationConfig` and `PromptExecutionStep`

Add per-token log-probabilities support with the top_logprobs generation config parameter and support returning per-token log-probabilities in the PromptExecutionStep. For more information please read the guide on How to request per-token log-probabilities

Improvements#

Improved Agent Spec tracing compatibility

Agent Spec tracing exports now serialize WayFlow Agent Spec plugin components with the proper plugin context and report a valid flow end branch when a flow finishes through a transition to None.
Scoped opt-in for authless MCP clients

Added authless_mcp_enabled() as a scoped context manager for local or test MCP clients that intentionally do not use authentication. The existing enable_mcp_without_auth() helper remains available, but now emits a SecurityWarning. Authless MCP use also emits a SecurityWarning when validation is bypassed.
Improved TLS defaults for MCP HTTP transports

SSETransport and StreamableHTTPTransport now use standard HTTPS certificate verification by default. SSEmTLSTransport and StreamableHTTPmTLSTransport now also verify that the server certificate matches the requested hostname unless this check is explicitly disabled.
Improved agent server access defaults

A2AServer.run(api_key=...) now enforces bearer-token authentication when an API key is provided. A2AServer and OpenAIResponsesServer now require an API key when binding to non-loopback hosts, while unauthenticated loopback development remains available with a warning. OpenAIResponsesServer no longer enables CORS by default and supports explicit allowed origins configuration.
Agent Spec component loading policies can be customized

AgentSpecLoader now accepts allowed_components and blocked_components so applications can control which Agent Spec and WayFlow plugin component types are allowed to load. This is useful for trusted deployments that need to opt in to runtime-sensitive components, and for stricter deployments that want to explicitly allow only a known component set. WayFlow extends PyAgentSpec’s default blocked components with WayFlow-specific runtime-sensitive components.
Removed ``starlette`` from third party dependencies

Direct starlette imports were removed in favor of FastAPI equivalent alternatives, so wayflowcore no longer relies on starlette as a direct, third party dependency.
Improved tool-result formatting across templates and model adapters

Built-in non-native prompt templates and model adapters now render tool results through a shared JSON-based formatter, which keeps tool-returned data more consistent across providers.

Documentation#

Added a new MCP server to browse the WayFlow documentation:

Added a new MCP server in examples/mcp/docs_mcp.py to let assistants browse the WayFlow documentation.

For more information, see the Docs MCP Server guide.
OpenAI-compatible embeddings now support API keys:

OpenAICompatibleEmbeddingModel now accepts an optional api_key (with OPENAI_API_KEY environment fallback) and sends it as an OpenAI-style Authorization: Bearer ... header.

Possibly Breaking Changes#

Authless MCP usage now requires explicit scoped opt-in

Unauthenticated MCP tools and toolboxes must now be constructed or loaded from Agent Spec inside authless_mcp_enabled() unless the transport provides authentication. The legacy enable_mcp_without_auth() helper remains available, but emits a SecurityWarning. Code that treats warnings as errors may need to catch or filter this warning for local tests.
MCP HTTPS transports now expect valid certificate configuration

SSETransport and StreamableHTTPTransport now use standard HTTPS certificate verification by default, and SSEmTLSTransport and StreamableHTTPmTLSTransport now verify the requested hostname by default. Deployments using self-signed certificates, custom certificate authorities, or certificates whose hostname does not match the MCP server URL may require certificate updates or transport configuration changes.
Agent servers require API keys on non-loopback hosts

A2AServer and OpenAIResponsesServer now require an api_key when binding to non-loopback hosts such as 0.0.0.0 or a public interface. A loopback host only accepts connections from the same machine, for example 127.0.0.1 or localhost. Unauthenticated local development on loopback hosts remains available with a warning.
MCP stdio transports are blocked by default in Agent Spec loaders

Configurations containing Agent Spec StdioTransport or WayFlow PluginStdioTransport will no longer load by default through AgentSpecLoader. WayFlow inherits the PyAgentSpec default blocked components and adds PluginStdioTransport. 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 those transport component types.
Summarization Transforms now do not do caching if the datastore is None

Previously when the datastore arguments of MessageSummarizationTransform and ConversationSummarizationTransform were set to None, an in-memory datastore was automatically created. Now, the in-memory datastore is created only if the datastore is left unspecified. If it is set to None then no caching happens.
VariableStep:

Introducing VariableStep, a comprehensive step for reading from and writing on variables. This feature provides users with an easier-to-use API to use Variable in flows, that may be used for centralizing the state and simplify the data flows. Especially, this may significantly simplify flows currently using the VariableReadStep and VariableWriteStep.

For more information check out how to use variables for shared state in flows.
Deprecated `json_body` parameter in RemoteTool/ApiCallStep:

Deprecated the json_body parameter in RemoteTool/ApiCallStep in favour of the data parameter. A DeprecationWarning will be raised whenever the json_body is tried to be set, and this parameter would be removed in version 26.2.0. If json_body is tried to be set, it will automatically be converted to data in RemoteTool/ApiCallStep. To migrate, simply switch the json_body keyword argument with data. data supports both JSON-objects and form-data for HTTP requests.

Bug fixes#

Fix: OpenAI-compatible Responses API requests now replay assistant text messages using the easy-input shape accepted by OpenAI and vLLM, avoiding validation errors when vLLM parses assistant history as output-message content. No-argument tools also emit an explicit object parameters schema for providers that reject empty tool parameter schemas.
Fix: agents now handle tool calls more robustly with OpenAI-compatible and Llama models, ignoring null streamed tool-call delta fields, normalizing model-produced arguments against declared tool schemas, and preserving non-string Llama tool-result values.
Fix: OCIGenAIModel now forwards LlmGenerationConfig parameters when using OciAPIType.OPENAI_CHAT_COMPLETIONS and OciAPIType.OPENAI_RESPONSES.
Fix: CanonicalizationMessageTransform now correctly handles assistant-role tool-result messages from runtime conversation history, which fixes parallel tool-calling turns for native tool-calling prompts such as OCI Google models.
Fix summarization transform persistence and multi-agent integration

MessageSummarizationTransform and ConversationSummarizationTransform now serialize the configuration required to deserialize prompt templates and resume serialized conversations correctly. Swarm and ManagerWorkers also now apply their component-level transforms during execution, making it possible to attach summarization transforms directly to these multi-agent components.

See the guide on using Swarm and ManagerWorkers to learn more about how component-level transforms are combined with prompt template transforms during execution.
Fix: conversations no longer replay already-materialized tool results when resuming manager-worker executions, which could previously duplicate internal send_message results and break continued execution after serialization.

WayFlow 26.1.1#

New features#

Tool output streaming:

Added a new event ToolExecutionStreamingChunkReceived to surface streamed tool chunks during tool execution. Tool output streaming is supported for MCP tools and for ServerTool with async-generator callables.

Check the guide on How to enable tool output streaming for more information.

Bug fixes#

Fix: MCP tools now support union/optional output schemas for the result field (e.g., anyOf including null). This prevents KeyError during schema parsing. (#70)
Fix: Gemini models with the OpenAiCompatible model now support native tool calling (#77)
Fix: MCP session persistence no longer collides when multiple MCP client transports (different servers/connections) are used within the same conversation.
Fix: Agent no longer ignores tool calls when the LLM attempts to both invoke a tool and respond directly to the user.

WayFlow 26.1.0#

Security#

Stricter environment for jinja templates rendering:

We now use a stricter version of the SandboxedEnvironment for rendering jinja templates. No access to object attributes is allowed, only key-based access to python dictionaries, lists, and main jinja LoopContext properties are allowed.

Check the guide on How to write secure prompts with Jinja templating for more information.

New features#

Added Flow Builder to simplify programmatic creation of WayFlow Flows.

The Flow Builder is a new chainable API to create WayFlow Flows more easily.

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

Added support for OCI responses API:

Added support for the new OCI responses API service. You can simply configure this on the OciGenAIModel:

from wayflowcore.models import OciGenAIModel, OciAPIType

llm = OciGenAIModel(
    ...,
    api_type=OciAPIType.OPENAI_RESPONSES, # to use the responses API service
)

Added User Confirmation for Tools in ToolBox:

Introduced a requires_confirmation flag to the base ToolBox Class. When enabled, this flag will pause tool execution of any of this toolbox’s tools and emit a ToolExecutionConfirmationStatus, requiring explicit user confirmation before proceeding. During confirmation, users may edit the tool’s arguments or provide a rejection reason. The tool executes only after confirmation is granted. This flag helps to let users enforce confirmation for the entire toolbox without having to set requires_confirmation=True on every tool it provides.
Agent Spec Tracing support:

Open Agent Specification Tracing (short: Agent Spec Tracing) is an extension of Agent Spec that standardizes how agent and flow executions emit traces. Wayflow now supports the emission of traces according to the Agent Spec Tracing standard.

For more information read the guide on How to Enable Tracing in WayFlow.
WayFlow Plugins:

Wayflow plugins allow users extending existing components (like Tools, Steps, etc.), or even creating new ones, and seamlessly integrate them in WayFlow and Agent Spec serialization and deserialization. For more information read the guide on how to use WayFlow plugins.
OpenAI Responses API Support:

OpenAICompatibleModel now supports 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 for Wayflow-powered workflows.

For more information check out the how-to guide on LLMs from different providers.
Serve agents via OpenAI Responses API:

Added OpenAIResponsesServer and ServerStorageConfig to host WayFlow agents behind OpenAI Responses-compatible endpoints, with optional persistence through supported datastores.

See the new how-to guide on serving agents for in-memory setup, datastore persistence, and Agent Spec export/reload examples.
Serve agents via A2A protocol: Introduced the A2AServer class for serving WayFlow conversational components using the A2A protocol.

For more information check out how to serve assistants with A2A protocol.

Improvements#

Added ``sensitive_headers`` in components that perform remote calls:

ApiCallStep, RemoteTool, and MCP RemoteBaseTransport now have a new attribute sensitive_headers. This new attribute should be used for headers that might contain sensitive information (e.g., authentication). Its value is merged with headers when the remote call is performed, and its value is never serialized.
Support list, dict and tuple output types in MCP tools:

MCP tools now support non-string output types (list of string, dictionary of strings and tuple of these types)

For more information see the guide on using MCP tools.
Python 3.14 support

Introduced support for python version 3.14.
Connection persistence for MCP servers:

MCP client sessions are now reused which improves MCP calls latency and enables uses where maintaining a session is required.

This does not require any change to existing assistants or execution loops.
Deserialization:

Deserialization of large conversations with many agents is now much faster due to optimizations in the deserialization code.
Long Message Summarization including Image Support

Added MessageSummarizationTransform which summarizes messages (including images) exceeding a configurable length threshold using a specified LLM and caches the summaries in a user-provided DataStore with configurable size, LRU eviction, and entry lifetime.
Long Conversation Summarization including Image Support

Added ConversationSummarizationTransform which summarizes conversations exceeding a configurable number of messages using a specified LLM and caches the summaries in a user-provided DataStore with configurable size, LRU eviction, and entry lifetime. This helps manage long conversation contexts by summarizing older parts while preserving recent messages.

Transforms can now be assigned to an agent through its constructor. (This is not supported in agentspec, so attempting to convert agents with transforms to agentspec will raise a NotImplementedError)
Improve Swarm prompt template, introduce HandoffMode and support multiple tool calls in Swarm:

Removed redundant agent descriptions from the Swarm template and added a guidance rule that encourages agents to hand off when appropriate. Introduced HandoffMode to Swarm. In addition to the existing modes (True → HandoffMode.OPTIONAL, False → HandoffMode.NEVER), a new mode HandoffMode.ALWAYS is now supported, requiring agents to always use the handoff mechanism when delegating tasks to other agents. Read more at HandoffMode. Added support for multiple tool calls in Swarm. The LLM may now emit multiple tool calls in a single response. These tools are executed sequentially, and all tool results are returned together.

This significantly reduces token usage and improves execution speed.
Support multiple tool calls for the manager agent in ManagerWorkers

Added support for multiple tool calls for the manager agent in ManagerWorkers. The LLM may now emit multiple tool calls in a single response. These tools are executed sequentially, and all tool results are returned together.
Support Swarm in Flows and ManagerWorkers:

Swarms and ManagerWorkers can be used in AgentExecutionStep and integrated into Flows. caller_input_mode is added to Swarms and ManagerWorkers, similar to Agents.
Support for multi level ManagerWorkers

Added support for multiple levels of ManagerWorkers where a worker in ManagerWorkers can itself be ManagerWorkers enabling the creation of hierarchical agent structures.
Added support for Gemini reasoning models (via OpenAI compatible API)

The extra_content returned by Gemini’s OpenAI-compatible APIs is now tracked as part of messages and tool_requests.

Possibly Breaking Changes#

Stricter environment for jinja templates rendering:

The new version of the Environment used to render templates could raise SecurityErrors on templates previously accepted.
Removed deprecated Agent/Flow.execute:

Removed the deprecated method of Agent/Flow.execute(conversation) in favor of conversation.execute().
Removed deprecated ChatHistoryContextProvider:

Removed the deprecated ChatHistoryContextProvider in favor of FlowContextProvider with a Flow with GetChatHistoryStep.
Removed deprecated begin_step_name parameter of Flow:

Removed the deprecated parameter begin_step_name of the Flow class. Please use begin_step, passing in a Step object instead.
Enforce valid tool names:

When creating any type of Tool, its name field must not contain whitespaces or special characters, so that LLM APIs do not return errors. See bug fix below.
- For now, a deprecation warning is raised; in the next cycle, an error will be thrown.
Deprecated ‘append’ parameter in PromptTemplate transform methods:

The append parameter in with_additional_post_rendering_transform and with_additional_pre_rendering_transform methods is deprecated. Use append_last instead. The append parameter will be removed in WayFlow 26.3.

Bug fixes#

Fixed several issues related to event tracing serialization when containing execution state:

Fixed an issue where FlowExecutionIterationStartedEvent and FlowExecutionIterationFinishedEvent could raise when the execution state contained values that are not supported by the serializer. The tracing helpers now fall back to stringifying those values while preserving container structures.
Recording of end span event in case of exception:

Fixed a bug where if an exception happened during a span, it would not be recorded and the span closing would raise an unwanted warning. Now properly records the exception as an ExceptionRaisedEvent and does not throw a warning.
Default values in agents inputs were ignored:

Fixed a bug where if agents had input descriptors with default values set, these defaults were ignored and not used when starting a conversation. Now default values of input descriptors are used if they are set, and no input entry with the descriptor name is passed to the start_conversation method.
Default values in tools outputs were ignored:

Fixed a bug where if tools had multiple output descriptors with default values set for some of them, these defaults were ignored and not set in the tool result if the tool execution did not produce a value for them. Tools that have a single output still ignore its default, as a return value is always assumed to be produced by the tool (possibly None).
Fixed warnings raised when LLM streaming generator was not properly closed:

Fixed a bug where streaming LLM generation in a chainlit app could raise warnings due to a non-closed generator. The generator is now properly closed and we silence the known issue on the httpx library.
Continuing an agent conversation after an exception was raised could cause an exception:

Fixed a bug where if an exception would occur during a tool, a sub-agent or a sub-flow call of an agent, the conversation could not be resumed afterwards because the conversation would miss the tool results of any calls that should have been done after the call that raised. It now posts results mentioning the call was skipped due to a previous failure.
Some Agent and Flow names could cause issues when used in multi-agent patterns:

Fixed a bug where Agents or Flows, whose name contains whitespaces or special characters, would crash upon sending a request to the LLM provider
- The cause was that internally, WayFlow converted a subagent of an Agent into a Tool, which is then converted to a JSON payload to submit to the LLM provider, which then returns an HTTP error if the tool’s name does not match a regex.
- Now, users may specify arbitrary names for Agents and Flows. Internally, when creating Tools out of subagents and subflows, their names would be sanitized.
Configuring Agents with PromptTemplates no longer requires custom instruction

Fixed a bug where instantiating an Agent with an agent_template, initial_message=None and custom_instruction=None would raise an exception. Now, users can fully specify the agent template without having to additionally specify initial messages or custom instructions.
Hand off in Swarms can only be done by the main agent in Optional Handoff Mode

Fixed a bug where handoff in Swarms was not restricted properly. The ability to handoff has been removed for agents that are sent send_message in Swarms, ensuring that only the main agent can perform handoffs in HandoffMode.OPTIONAL mode.
Fixed tool calling for OCI models

Resolved an issue that sent incorrectly formatted chat histories to OCI endpoints, degrading tool-calling and agentic performance for google and cohere models. All OCI models can now more reliably and efficiently leverage tool calling.
Fixed agent termination when ``caller_input_mode`` was set to never

Corrected an issue where agents without outputs and caller_input_mode=CallerInputMode.NEVER would repeatedly iterate until the maximum limit. Agents can now better complete the task and exit as expected.
Structured generation with nested ObjectProperties

Fixed a bug that was raising an error on structured generation of nested ObjectProperties with OpenAI-compatible Models.

WayFlow 25.4.2#

New features#

Agent Spec structured generation: Open Agent Specification introduced Structured Generation in version 25.4.2. Support for this new Agent Spec feature was added in converters.

For more information check out the how-to guide on Structured Generation
Added Tool Confirmation before Execution: Introduced a requires_confirmation flag to the base Tool Class. When enabled, this flag will pause tool execution and emit a ToolExecutionConfirmationStatus, requiring explicit user confirmation before proceeding. During confirmation, users may edit the tool’s arguments or provide a rejection reason. The tool executes only after confirmation is granted.

For more information check out the corresponding how-to guide
Added SplitPromptOnMarkerMessageTransform: Introduced a new Message Transform specialization that splits prompts on a marker into multiple messages with the same role.

We thank @richl9 for the contribution!

Bug fixes#

Flow input and output descriptors

Fixed a bug where Flow input and output descriptors were sometimes ignored:
- All the inputs required by the steps that compose the Flow were used instead of the input descriptors provided.
- The intersection of all the outputs generated by any branch in the Flow was used instead of the output descriptors provided.
The behavior is now:
- Input descriptors can now be a subset of all the inputs required by the steps that compose the Flow, as long as the missing step inputs have a default value.
- Output descriptors can be a subset of the intersection of all the outputs generated by any branch in the Flow. This is now correctly reflected also in other parts of the package.
Datastore validation

Fixed a bug which might cause OracleDatabaseDatastore to raise an exception due to concurrent changes and unsupported data types on unrelated parts of the schema, i.e., tables and columns that are not included in the datastore schema itself.

Miscellaneous#

Dependency Security Updates: Upgraded MCP to 1.17.0 and PyYAML to 6.0.3 to resolve known security vulnerabilities, including GHSA-j975-95f5-7wqh, GHSA-3qhf-m339-9g5v, GHSA-6757-jp84-gxfx, and GHSA-8q59-q68h-6hv4.

Improvements#

Use execution statuses to interact with the components Users can now directly see the conversation state and interact with the agent via the execution status.

agent = Agent(...)
tools_dict = {...}

conversation: Conversation = agent.start_conversation()

while True:
    status = conversation.execute()

    if isintance(status, UserMessageRequestStatus):
        print('Agent >> ', status.message.content)
        user_response = input('User >> ')
        status.submit_user_response(user_response)
    elif isinstance(status, ToolRequestStatus):
        for tool_request in status.tool_requests:
            tool_result = ToolResult(
                tool_id=tool_request.tool_request_id,
                content=tools_dict[tool_request.name](**tool_request.args)
            )
            status.submit_tool_result(tool_result)
    elif isinstance(status, FinishedStatus):
        break

For more information check out Reference Sheet

WayFlow 25.4.1 — Initial release#

WayFlow is here: Build advanced AI-powered assistants with ease!

With this release, WayFlow provides all you need for building AI-powered assistants, supporting structured workflows, autonomous agents, multi-agent collaboration, human-in-the-loop capabilities, and tool-based extensibility. Modular design ensures you can rapidly build, iterate, and customize both simple and complex assistants for any task.

Explore further: