Execute Agent Spec Configuration with WayFlow#

python-icon Download Python Script

Python script/notebook for this guide.

Execute Agent Spec with WayFlow how-to script

Prerequisites

This guide assumes familiarity with Agent Spec and exporting Agent Spec configurations.

This guide will show you how to:

  1. Define the execution of tools in a tool registry.

  2. Load an Agent Spec configuration with the WayFlow adapter.

  3. Run the assistant and interact with it.

This guide shows you how to use a minimal Agent setup with a single tool for performing multiplications. You can use the same code structure to load and run more complex assistants.

1. Install packages#

To run the examples in this guide, make sure that wayflowcore is installed.

For more details, refer to the WayFlow Agent Spec adapter API documentation.

2. Define the tool registry#

Before loading the configuration, you need to define the tool registry. This registry specifies how to execute each tool since the implementation of tools is not included in the Agent Spec assistant configuration.

The example below shows how to register a single tool that performs multiplications. Adapt this pattern to register all the tools your assistant requires.

This guide uses the simplest type of tool, ServerTool. For more advanced tool types, refer to the Agent Spec Language specification.

1@tool(description_mode="only_docstring")
2def multiplication_tool(a: int, b: int) -> int:
3    """Tool that allows to compute multiplications."""
4    return a * b
5
6tool_registry = {
7    "multiplication_tool": multiplication_tool,
8}

3. Load the Agent Spec configuration#

Now load the agent configuration. The configuration starts by defining two components: multiplication_tool and vllm_config. These are referenced in the agent definition later.

 1AgentSpec_CONFIG = """
 2  $referenced_components:
 3    multiplication_tool:
 4      component_type: ServerTool
 5      description: Tool that allows to compute multiplications
 6      id: multiplication_tool
 7      inputs:
 8      - title: a
 9        type: integer
10      - title: b
11        type: integer
12      name: multiplication_tool
13      outputs:
14      - title: product
15        type: integer
16    vllm_config:
17      component_type: VllmConfig
18      default_generation_parameters: null
19      description: null
20      id: vllm_config
21      model_id: meta-llama/Meta-Llama-3.1-8B-Instruct
22      name: llama-3.1-8b-instruct
23      url: http://insert-your-model-url-here
24  component_type: Agent
25  llm_config:
26    $component_ref: vllm_config
27  name: Math homework assistant
28  system_prompt: You are an assistant for helping with math homework.
29  tools:
30  - $component_ref: multiplication_tool
31  agentspec_version: 25.4.1
32"""

Loading the configuration to the WayFlow executor is simple as long as the tool_registry has been defined.

1from wayflowcore.agentspec import AgentSpecLoader
2
3loader = AgentSpecLoader(tool_registry=tool_registry)
4assistant = loader.load_yaml(AgentSpec_CONFIG)

4. Run the assistant#

Start by creating a conversation. Then prompt the user for some input. The assistant will respond until you interrupt the process with Ctrl+C. Messages of type TOOL_REQUEST and TOOL_RESULT are also displayed. These messages help you understand how the assistant decides to act.

For more details, see the API Reference.

 1from wayflowcore import MessageType
 2from wayflowcore import Agent
 3
 4# %%
 5# Or with an execution loop
 6def run_agent_in_command_line(assistant: Agent):
 7    conversation = assistant.start_conversation()
 8    message_idx = 0
 9    while True:
10        user_input = input("\nUSER >>> ")
11        conversation.append_user_message(user_input)
12        conversation.execute()
13        messages = conversation.get_messages()
14        for message in messages[message_idx + 1 :]:
15            if message.message_type == MessageType.TOOL_REQUEST:
16                print(f"\n{message.message_type.value} >>> {message.tool_requests}")
17            else:
18                print(f"\n{message.message_type.value} >>> {message.content}")
19        message_idx = len(messages)
20
21# run_agent_in_command_line(assistant)
22# ^ uncomment and execute

You can also run a non-conversational flow. In that case, the execution loop could be implemented as follows:

1def run_agent_non_conversational(assistant: Agent):
2    conversation = assistant.start_conversation({ "some_input_name": "some_input_value"})
3    conversation.execute()
4    for output_name, output_value in conversation.state.input_output_key_values.items():
5        print(f"{output_name} >>> \n{output_value}")
6
7# run_agent_non_conversational(assistant)
8# ^ uncomment and execute

Agent Spec Exporting/Loading#

You can export the assistant configuration to its Agent Spec configuration using the AgentSpecExporter.

from wayflowcore.agentspec import AgentSpecExporter

config = AgentSpecExporter().to_json(assistant)

And load it back using the AgentSpecLoader.

from wayflowcore.agentspec import AgentSpecLoader

tool_registry= {"multiplication_tool": multiplication_tool}
new_assistant = AgentSpecLoader(tool_registry=tool_registry).load_json(config)

Next steps#

In this guide, you learned how to:

  1. Install the Agent Spec adapter for WayFlow.

  2. Define tool execution using a tool registry.

  3. Load an Agent Spec configuration with the WayFlow adapter.

  4. Run the assistant and interact with it in a conversation loop.

You may now proceed to:

Full code#

Click on the card at the top of this page to download the full code for this guide or copy the code below.

  1# Copyright © 2025 Oracle and/or its affiliates.
  2#
  3# This software is under the Universal Permissive License
  4# %%[markdown]
  5# WayFlow Code Example - How to Execute Agent Spec with WayFlow
  6# -------------------------------------------------------------
  7
  8# How to use:
  9# Create a new Python virtual environment and install the latest WayFlow version.
 10# ```bash
 11# python -m venv venv-wayflowcore
 12# source venv-wayflowcore/bin/activate
 13# pip install --upgrade pip
 14# pip install "wayflowcore==26.1" 
 15# ```
 16
 17# You can now run the script
 18# 1. As a Python file:
 19# ```bash
 20# python howto_execute_agentspec_with_wayflowcore.py
 21# ```
 22# 2. As a Notebook (in VSCode):
 23# When viewing the file,
 24#  - press the keys Ctrl + Enter to run the selected cell
 25#  - or Shift + Enter to run the selected cell and move to the cell below# (UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl) or Apache License
 26# 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0), at your option.
 27
 28
 29from wayflowcore.agentspec import AgentSpecLoader
 30from wayflowcore.tools import tool
 31
 32
 33# %%[markdown]
 34## AgentSpec Configuration
 35
 36# %%
 37AgentSpec_CONFIG = """
 38  $referenced_components:
 39    multiplication_tool:
 40      component_type: ServerTool
 41      description: Tool that allows to compute multiplications
 42      id: multiplication_tool
 43      inputs:
 44      - title: a
 45        type: integer
 46      - title: b
 47        type: integer
 48      name: multiplication_tool
 49      outputs:
 50      - title: product
 51        type: integer
 52    vllm_config:
 53      component_type: VllmConfig
 54      default_generation_parameters: null
 55      description: null
 56      id: vllm_config
 57      model_id: meta-llama/Meta-Llama-3.1-8B-Instruct
 58      name: llama-3.1-8b-instruct
 59      url: http://insert-your-model-url-here
 60  component_type: Agent
 61  llm_config:
 62    $component_ref: vllm_config
 63  name: Math homework assistant
 64  system_prompt: You are an assistant for helping with math homework.
 65  tools:
 66  - $component_ref: multiplication_tool
 67  agentspec_version: 25.4.1
 68"""
 69
 70# %%[markdown]
 71## Tool Registry Setup
 72
 73# %%
 74@tool(description_mode="only_docstring")
 75def multiplication_tool(a: int, b: int) -> int:
 76    """Tool that allows to compute multiplications."""
 77    return a * b
 78
 79tool_registry = {
 80    "multiplication_tool": multiplication_tool,
 81}
 82
 83# %%[markdown]
 84## Load AgentSpec Configuration
 85
 86# %%
 87from wayflowcore.agentspec import AgentSpecLoader
 88
 89loader = AgentSpecLoader(tool_registry=tool_registry)
 90assistant = loader.load_yaml(AgentSpec_CONFIG)
 91
 92# %%[markdown]
 93## Execution Loop Conversational
 94
 95# %%
 96from wayflowcore import MessageType
 97from wayflowcore import Agent
 98
 99# %%
100# Or with an execution loop
101def run_agent_in_command_line(assistant: Agent):
102    conversation = assistant.start_conversation()
103    message_idx = 0
104    while True:
105        user_input = input("\nUSER >>> ")
106        conversation.append_user_message(user_input)
107        conversation.execute()
108        messages = conversation.get_messages()
109        for message in messages[message_idx + 1 :]:
110            if message.message_type == MessageType.TOOL_REQUEST:
111                print(f"\n{message.message_type.value} >>> {message.tool_requests}")
112            else:
113                print(f"\n{message.message_type.value} >>> {message.content}")
114        message_idx = len(messages)
115
116# run_agent_in_command_line(assistant)
117# ^ uncomment and execute
118
119# %%[markdown]
120## Execution Loop Non Conversational
121
122# %%
123def run_agent_non_conversational(assistant: Agent):
124    conversation = assistant.start_conversation({ "some_input_name": "some_input_value"})
125    conversation.execute()
126    for output_name, output_value in conversation.state.input_output_key_values.items():
127        print(f"{output_name} >>> \n{output_value}")
128
129# run_agent_non_conversational(assistant)
130# ^ uncomment and execute
131
132# %%[markdown]
133## Export Config to Agent Spec
134
135# %%
136from wayflowcore.agentspec import AgentSpecExporter
137
138config = AgentSpecExporter().to_json(assistant)
139
140# %%[markdown]
141## Load Agent Spec Config
142
143# %%
144from wayflowcore.agentspec import AgentSpecLoader
145
146tool_registry= {"multiplication_tool": multiplication_tool}
147new_assistant = AgentSpecLoader(tool_registry=tool_registry).load_json(config)