Execute Agent Spec Configuration with WayFlow#
Prerequisites
This guide assumes familiarity with Agent Spec and exporting Agent Spec configurations.
This guide will show you how to:
Define the execution of tools in a tool registry.
Load an Agent Spec configuration with the WayFlow adapter.
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:
Install the Agent Spec adapter for WayFlow.
Define tool execution using a tool registry.
Load an Agent Spec configuration with the WayFlow adapter.
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)