WayFlow

WayFlow provides a collection of goal-oriented, concrete guides designed to help you complete specific tasks when building AI assistants. These guides cover several key domains:

• Building Assistants: Creating Agents, Flows, and multi-agent patterns (Hierarchical, Swarm, Manager-Workers).
• Tools in Assistants: Equipping assistants with server-side, client-side, remote API, or Model Context Protocol (MCP) tools.
• Configuration and State Management: Managing agent specs, serialization, plugins, tracing, and the event system.
• Data in Assistants: Connecting to data stores, using embedding models, managing shared state via variables, and building RAG-powered assistants.
• Assistant Testing and Evaluation: Evaluating both assistants and individual conversations.

Each code example provided in the guides is self-contained and can be executed using WayFlow.

WayFlow is a Python library for building AI-powered assistants using two primary patterns:

1. Agents: Flexible, autonomous entities that use LLMs to drive interaction.
2. Flows: Structured, predictable sequences of steps for specific tasks.

Key features include:

• Interoperability: Works with various LLM vendors.
• Reusability: Supports composable components and a standard library of plan steps.
• Openness: Serves as the reference runtime implementation for the Open Agent Spec.

Tool output streaming allows a tool to produce intermediate outputs while it is still running, rather than waiting for the entire execution to complete. This is useful for UIs to display partial results in near real time.

Key Mechanics:

• Chunk Events: When streaming is enabled, WayFlow emits ToolExecutionStreamingChunkReceivedEvent as the tool makes progress.
• Final Result: The tool's final output is the last value produced (the completed tool result). Earlier values are treated as streamed chunks and are not considered the final result.
• Implementation: To enable streaming, define the tool as an async generator (an async callable that uses yield instead of return).

A Flow is a type of assistant composed of individual Steps connected in a coherent sequence of actions. Unlike an Agent, which typically maintains chat history for multi-turn conversations, a Flow is a structured way to execute specific business processes by chaining discrete, often stateless, functional steps.

Common step types include:

• InputMessageStep: Gathers input from the user.
• ToolExecutionStep: Runs a tool (like a Python function) to fetch or manipulate data.
• PromptExecutionStep: Executes a prompt using an LLM, supporting data insertion from previous steps via Jinja templating.
• OutputMessageStep: Displays information to the user.

An ExecutionInterrupt allows you to intervene in an assistant's execution. You can define conditions to stop or pause execution and trigger a custom callback function. Common use cases include:

• Reaching a time limit.
• Exceeding a maximum number of tokens.

WayFlow provides two primary types of AI-powered assistants, which can be composed to solve complex tasks:

• Flows: Structured assistants that follow a pre-defined, prescriptive task completion process. They are composed of individual steps connected in a sequence and are ideal for business processes where control and predictability are required.
• Agents: Conversational assistants that can autonomously plan, think, act, and execute tools. They are more flexible and can interact with users and other assistants to solve requests through conversational interfaces.

Agents can be integrated into Flows using an AgentExecutionStep.

Extended components are standard Agent Spec components that have been augmented with additional fields. These are specifically designed to allow developers to export their WayFlow assistants to Agent Spec while retaining extra metadata or configuration.

Available extended components include:

• ExtendedAgent
• ExtendedFlow
• ExtendedToolNode
• ExtendedLlmNode
• ExtendedMapNode

Maintain a conversational yet formal tone by following these rules:

• Voice: Use the second-person singular (you). Use we only when referring to the developers. Prefer active voice over passive voice (e.g., use We recommend instead of It is recommended).
• Avoid Marketing Language: Do not use phrases like It’s simple or It’s easy.
• Avoid Contractions: Do not use it’s, you’ll, or you’re.
• Gender Neutrality: Avoid gender-specific pronouns (he, she, his, hers). Use neutral plural subjects like developers or users.
• Word Choice: Avoid using the word get in a casual sense (e.g., use were included instead of got included).

For advanced workflows, you can combine InputMessageStep with BranchingStep to create decision logic. For example, you can ask for confirmation (e.g., "y/n") and use a BranchingStep to route the flow to either a ToolExecutionStep or a different path based on that input.

from wayflowcore import Flow, InputMessageStep, BranchingStep, ToolExecutionStep

# Example of a flow that asks for confirmation before a tool call
def create_complex_flow():
    flow = Flow()
    flow.add_step(InputMessageStep(message_template="Confirm action? (y/n)"))
    
    # Branch based on the user's response
    flow.add_step(BranchingStep(
        branching_map={
            "y": "tool_step",
            "n": "skip_step"
        }
    ))
    
    flow.add_step(ToolExecutionStep(name="my_tool"), name="tool_step")
    return flow