Agent Spec

https://oracle.github.io/agent-spec
Admin
Agent Spec (Open Agent Specification) is a portable, platform-agnostic configuration language for...
Tokens:360,399
Snippets:1,901
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Example: Article LLM Summary Flow Setup

Source: https://oracle.github.io/agent-spec/development/api/flows

Sets up the initial nodes and properties for an example flow that summarizes articles using LLMs. It defines properties for articles and LLM checks, and instantiates LlmNode, BranchingNode, StartNode, and EndNode.

```python
from pyagentspec.property import BooleanProperty, StringProperty, ListProperty
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.nodes import EndNode, StartNode, ParallelMapNode, LlmNode, BranchingNode
from pyagentspec.flows.node import Node

article_property = StringProperty(title="article")
is_llm_article_property = StringProperty(title="is_article")
llm_node = LlmNode(
    name="check_if_article_talks_about_llms_node",
    prompt_template="Look at this article: {{article}}. Does it talk about LLMs? Answer `yes` or `no`.",
    llm_config=llm_config, # Assuming llm_config is defined elsewhere
    inputs=[article_property],
    outputs=[is_llm_article_property],
)

branching_node = BranchingNode(
    name="decide_if_we_should_return_the_article",
    mapping={"yes": "yes"},
    inputs=[is_llm_article_property],
)

start_node = StartNode(name="start", inputs=[article_property])
end_node_with_output = EndNode(name="end_with_output", outputs=[article_property])
```

--------------------------------

### Python Example: Setting up an Agent and Flow

Source: https://oracle.github.io/agent-spec/25.4.1/agentspec/language_spec_25_4_1

This Python code snippet demonstrates how to define and instantiate various components for building an agent-based flow. It includes creating properties, tools, an agent with a system prompt and tools, and then assembling these into a flow with start, agent, and end nodes connected by control and data flow edges. This setup is fundamental for defining agentic workflows.

```python
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.agent import Agent
from pyagentspec.property import Property
from pyagentspec.flows.nodes import AgentNode, StartNode, EndNode
from pyagentspec.tools import ServerTool

# Assuming llm_config is defined elsewhere
# llm_config = ...

query_property = Property(json_schema={"title": "query", "type": "string"})
search_results_property = Property(
    json_schema={"title": "search_results", "type": "array", "items": {"type": "string"}}
)

search_tool = ServerTool(
    name="search_tool",
    description=(
       "This tool runs a web search with the given query "
       "and returns the most relevant results"
    ),
    inputs=[query_property],
    outputs=[search_results_property],
)

agent = Agent(
    name="Search agent",
    llm_config=llm_config,
    system_prompt=(
        "Your task is to gather the required information for the user: {{query}}"
    ),
    tools=[search_tool],
    outputs=[search_results_property],
)

start_node = StartNode(name="start", inputs=[query_property])
end_node = EndNode(name="end", outputs=[search_results_property])

agent_node = AgentNode(
    name="Search agent node",
    agent=agent,
)

flow = Flow(
    name="Search agent flow",
    start_node=start_node,
    nodes=[start_node, agent_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="start_to_agent", from_node=start_node, to_node=agent_node),
        ControlFlowEdge(name="agent_to_end", from_node=agent_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="query_edge",
            source_node=start_node,
            source_output="query",
            destination_node=agent_node,
            destination_input="query",
        ),
        DataFlowEdge(
            name="search_results_edge",
            source_node=agent_node,
            source_output="search_results",
            destination_node=end_node,
            destination_input="search_results"
        ),
    ],
)
```

--------------------------------

### Complete WayFlow Agent Spec Setup and Execution Example (Python)

Source: https://oracle.github.io/agent-spec/25.4.1/howtoguides/howto_execute_agentspec_with_wayflow

This comprehensive Python script demonstrates setting up a WayFlow agent with a custom tool ('multiplication_tool') and then running it in a conversational loop. It includes defining the agent configuration, registering the tool, loading the agent spec, and handling the interaction. Dependencies include `wayflowcore` and standard libraries like `logging` and `warnings`.

```Python
import logging
import warnings

from wayflowcore import MessageType
from wayflowcore.agentspec import AgentSpecLoader
from wayflowcore.tools import ServerTool

warnings.filterwarnings("ignore")
logging.basicConfig(level=logging.CRITICAL)

AGENTSPEC_CONFIG = """
component_type: Agent
id: e52d2c57-0bdc-4f25-948a-2e9d9f670008
name: Math homework assistant
description: null
metadata: {}
inputs: []
outputs: []
llm_config:
  component_type: VllmConfig
  id: vllm_config
  name: llama-3.1-8b-instruct
  description: null
  metadata: {}
  default_generation_parameters: {}
  url: LLAMA_PUBLIC_ENDPOINT
  model_id: meta-llama/Meta-Llama-3.1-8B-Instruct
system_prompt: You are an assistant for helping with math homework.
tools:
- component_type: ServerTool
  id: multiplication_tool
  name: multiplication_tool
  description: Tool that allows to compute multiplications
  metadata: {}
  inputs:
  - title: a
    type: integer
  - title: b
    type: integer
  outputs:
  - title: product
    type: integer
"""

multiplication_tool = ServerTool(
    name="multiplication_tool",
    description="Tool that allows to compute multiplications",
    parameters={"a": {"type": "integer"}, "b": {"type": "integer"}},
    output={"title": "product", "type": "integer"},
    func=lambda a, b: a * b,
)

tool_registry = {
    "multiplication_tool": multiplication_tool,
}

loader = AgentSpecLoader(tool_registry=tool_registry)
assistant = loader.load_yaml(AGENTSPEC_CONFIG)

if __name__ == "__main__":
    conversation = assistant.start_conversation()
    message_idx = 0
    while True:
        user_input = input("\nUSER >>> ")
        conversation.append_user_message(user_input)
        assistant.execute(conversation)
        messages = conversation.get_messages()
        for message in messages[message_idx + 1 :]:
            if message.message_type == MessageType.TOOL_REQUEST:
                print(f"\n{message.message_type.value} >>> {message.tool_requests}")
            else:
                print(f"\n{message.message_type.value} >>> {message.content}")
        message_idx = len(messages)
```

--------------------------------

### ToolNode Example: Constructing a Square Root Flow

Source: https://oracle.github.io/agent-spec/25.4.1/api/flows

This Python code demonstrates how to create a complete flow using ToolNode. It defines properties, a server tool, start and end nodes, and connects them using ControlFlowEdge and DataFlowEdge to compute the square root of a number.

```python
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.nodes import ToolNode, StartNode, EndNode
from pyagentspec.tools import ServerTool
from pyagentspec.property import Property

x_property = Property(json_schema={"title": "x", "type": "number"})
x_square_root_property = Property(
    json_schema={"title": "x_square_root", "type": "number"}
)
square_root_tool = ServerTool(
    name="compute_square_root",
    description="Computes the square root of a number",
    inputs=[x_property],
    outputs=[x_square_root_property],
)
start_node = StartNode(name="start", inputs=[x_property])
end_node = EndNode(name="end", outputs=[x_square_root_property])
tool_node = ToolNode(name="", tool=square_root_tool)
flow = Flow(
    name="Compute square root flow",
    start_node=start_node,
    nodes=[start_node, tool_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="start_to_tool", from_node=start_node, to_node=tool_node),
        ControlFlowEdge(name="tool_to_end", from_node=tool_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="x_edge",
            source_node=start_node,
            source_output="x",
            destination_node=tool_node,
            destination_input="x",
        ),
        DataFlowEdge(
            name="x_square_root_edge",
            source_node=tool_node,
            source_output="x_square_root",
            destination_node=end_node,
            destination_input="x_square_root"
        ),
    ],
)
```

--------------------------------

### Implement a Simple MCP Server in Python

Source: https://oracle.github.io/agent-spec/25.4.1/howtoguides/howto_mcp

This Python code snippet defines and starts a simple MCP server using the FastMCP framework. It exposes two tools: `get_user_session` for retrieving user session details and `get_payslips` for fetching payslip information based on a PersonId. The server is configured to run with Server-Sent Events (SSE) transport. Ensure the `mcp` library is installed.

```python
from mcp.server.fastmcp import FastMCP

PAYSLIPS = [
    {
        "Amount": 7612,
        "Currency": "USD",
        "PeriodStartDate": "2025/05/15",
        "PeriodEndDate": "2025/06/15",
        "PaymentDate": "",
        "DocumentId": 2,
        "PersonId": 2,
    },
    {
        "Amount": 5000,
        "Currency": "CHF",
        "PeriodStartDate": "2024/05/01",
        "PeriodEndDate": "2024/06/01",
        "PaymentDate": "2024/05/15",
        "DocumentId": 1,
        "PersonId": 1,
    },
    {
        "Amount": 10000,
        "Currency": "EUR",
        "PeriodStartDate": "2025/06/15",
        "PeriodEndDate": "2025/10/15",
        "PaymentDate": "",
        "DocumentsId": 3,
        "PersonId": 3,
    },
]

def create_server(host: str, port: int):
    """Create and configure the MCP server"""
    server = FastMCP(
        name="Example MCP Server",
        instructions="A MCP Server.",
        host=host,
        port=port,
    )

    @server.tool(description="Return session details for the current user")
    def get_user_session():
        print("called get_user_session")
        return {
            "PersonId": "1",
            "Username": "Bob.b",
            "DisplayName": "Bob B",
        }

    @server.tool(description="Return payslip details for a given PersonId")
    def get_payslips(PersonId: int):
        return [payslip for payslip in PAYSLIPS if payslip["PersonId"] == int(PersonId)]

    return server


def start_mcp_server() -> str:
    host: str = "localhost"
    port: int = 8080
    server = create_server(host=host, port=port)
    server.run(transport="sse")

    return f"http://{host}:{port}/sse"

# mcp_server_url = start_mcp_server() # <--- Move the code above to a separate file then uncomment

```

--------------------------------

### Python Example: Create a Simple Flow with LLMNode

Source: https://oracle.github.io/agent-spec/25.4.1/agentspec/language_spec_25_4_1

This Python code demonstrates how to construct a simple agent flow using the pyagentspec library. It defines properties, start, end, and LLM nodes, and then connects them using control and data flow edges to create a sequence of operations for prompting an LLM and processing its output.

```python
from pyagentspec.property import Property
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.nodes import LlmNode, StartNode, EndNode

prompt_property = Property(
    json_schema={"title": "prompt", "type": "string"}
)
llm_output_property = Property(
    json_schema={"title": "llm_output", "type": "string"}
)

start_node = StartNode(name="start", inputs=[prompt_property])
end_node = EndNode(name="end", outputs=[llm_output_property])

# Assuming llm_config is defined elsewhere
llm_config = {}
llm_node = LlmNode(
    name="simple llm node",
    llm_config=llm_config,
    prompt_template="{{prompt}}",
    inputs=[prompt_property],
    outputs=[llm_output_property],
)

flow = Flow(
    name="Simple prompting flow",
    start_node=start_node,
    nodes=[start_node, llm_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="start_to_llm", from_node=start_node, to_node=llm_node),
        ControlFlowEdge(name="llm_to_end", from_node=llm_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="prompt_edge",
            source_node=start_node,
            source_output="prompt",
            destination_node=llm_node,
            destination_input="prompt",
        ),
        DataFlowEdge(
            name="llm_output_edge",
            source_node=llm_node,
            source_output="llm_output",
            destination_node=end_node,
            destination_input="llm_output"
        ),
    ],
)
```

--------------------------------

### Example Agent Spec JSON Representation

Source: https://oracle.github.io/agent-spec/development/howtoguides/howto_mcp

An example of the JSON output generated by serializing an Agent Spec object. This structure details the agent's components, LLM configuration, and toolboxes.

```json
{
    "component_type": "Agent",
    "id": "420c4c4a-c6ae-48de-a7b3-6e3e7c314149",
    "name": "Agent using MCP",
    "description": null,
    "metadata": {},
    "inputs": [],
    "outputs": [],
    "llm_config": {
        "component_type": "VllmConfig",
        "id": "d4436c2b-e286-44cd-b89b-0ebaefbe3ee7",
        "name": "llm",
        "description": null,
        "metadata": {},
        "default_generation_parameters": null,
        "url": "url",
        "model_id": "model_id"
    },
    "system_prompt": "Use tools at your disposal to assist the user.",
    "tools": [],
    "toolboxes": [
        {
            "component_type": "MCPToolBox",
            "id": "f263d71e-4e3e-4bc5-ba86-8ec69634d925",
            "name": "Payslip MCP ToolBox",
            "description": null,
            "metadata": {},
            "client_transport": {
                "component_type": "SSETransport",
                "id": "8e723672-b7f7-4698-bfe0-c66ab1525043",
                "name": "MCP Client",
                "description": null,
                "metadata": {},
                "session_parameters": {
                    "read_timeout_seconds": 60.0
                },
                "url": "http://localhost:8080/sse",
                "headers": null
            },
            "tool_filter": null
        }
    ],
    "human_in_the_loop": true,
    "agentspec_version": "25.4.2"
}
```

--------------------------------

### Agent Flow Example

Source: https://oracle.github.io/agent-spec/25.4.1/api/flows

A comprehensive example demonstrating the creation of an agent flow for language detection, including nodes, agents, and control/data flow connections.

```APIDOC
## Example: Language Detection Flow

This example illustrates how to construct a flow that detects the language of user input and routes it to appropriate end nodes.

### Setup

```python
from pyagentspec.agent import Agent
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.nodes import AgentNode, BranchingNode, StartNode, EndNode
from pyagentspec.property import Property

# Assume llm_config is defined elsewhere
# llm_config = {...}

languages_to_branch_name = {
    "english": "ENGLISH",
    "spanish": "SPANISH",
    "italian": "ITALIAN",
}

language_property = Property(
    json_schema={"title": "language", "type": "string"}
)

agent = Agent(
    name="Language detector agent",
    llm_config=llm_config,
    system_prompt=(
        "Your task is to understand the language spoken by the user."
        "Please output only the language in lowercase and submit."
    ),
    outputs=[language_property],
)

start_node = StartNode(name="start")
english_end_node = EndNode(
    name="english end", branch_name=languages_to_branch_name["english"]
)
sspanish_end_node = EndNode(
    name="spanish end", branch_name=languages_to_branch_name["spanish"]
)
italian_end_node = EndNode(
    name="italian end", branch_name=languages_to_branch_name["italian"]
)
unknown_end_node = EndNode(name="unknown language end", branch_name="unknown")

branching_node = BranchingNode(
    name="language check",
    mapping=languages_to_branch_name,
    inputs=[language_property]
)

agent_node = AgentNode(
    name="User input agent node",
    agent=agent,
)

assistant = Flow(
    name="Check access flow",
    start_node=start_node,
    nodes=[
        start_node,
        agent_node,
        branching_node,
        english_end_node,
        spanish_end_node,
        italian_end_node,
        unknown_end_node,
    ],
    control_flow_connections=[
        ControlFlowEdge(
            name="start_to_agent", from_node=start_node, to_node=agent_node
        ),
        ControlFlowEdge(
            name="agent_to_branching", from_node=agent_node, to_node=branching_node
        ),
        ControlFlowEdge(
            name="branching_to_english_end",
            from_node=branching_node,
            from_branch=languages_to_branch_name["english"],
            to_node=english_end_node,
        ),
        ControlFlowEdge(
            name="branching_to_spanish_end",
            from_node=branching_node,
            from_branch=languages_to_branch_name["spanish"],
            to_node=spanish_end_node,
        ),
        ControlFlowEdge(
            name="branching_to_italian_end",
            from_node=branching_node,
            from_branch=languages_to_branch_name["italian"],
            to_node=italian_end_node,
        ),
        ControlFlowEdge(
            name="branching_to_unknown_end",
            from_node=branching_node,
            from_branch=BranchingNode.DEFAULT_BRANCH,
            to_node=unknown_end_node,
        ),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="language_edge",
            source_node=agent_node,
            source_output="language",
            destination_node=branching_node,
            destination_input="language",
        ),
    ],
)

```

### Flow Structure

- **Start Node**: Initiates the flow.
- **Agent Node**: Processes user input using the language detection agent.
- **Branching Node**: Directs the flow based on the detected language.
- **End Nodes**: Terminate the flow for each identified language (English, Spanish, Italian) and a default "unknown" branch.

### Connections

- **Control Flow**: Defines the sequence of node execution.
- **Data Flow**: Transmits the detected language from the agent node to the branching node.
```

--------------------------------

### FlowNode Example - Python

Source: https://oracle.github.io/agent-spec/25.4.1/api/flows

Demonstrates how to use the FlowNode to encapsulate a reusable subflow for estimating numerical values using an LLM. This example showcases the definition of tools, prompts, properties, nodes, and the connections within the subflow.

```python
>>> from pyagentspec.property import Property
>>> from pyagentspec.flows.flow import Flow
>>> from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
>>> from pyagentspec.flows.nodes import MapNode, LlmNode, ToolNode, StartNode, EndNode
>>> from pyagentspec.tools import ServerTool
>>> duplication_tool = ServerTool(
...     name="duplication_tool",
...     description="",
...     inputs=[
...         Property(
...             json_schema={"title": "element", "description": "", "type": "string"}
...         ),
...         Property(
...             json_schema={"title": "n", "description": "", "type": "integer"}
...         ),
...     ],
...     outputs=[
...         Property(
...             json_schema={
...                 "title": "flow_iterable_queries",
...                 "type": "array",
...                 "items": {"type": "string"}
...             },
...         )
...     ],
... )
>>> reduce_tool = ServerTool(
...     name="reduce_tool",
...     description="",
...     inputs=[
...         Property(
...             json_schema={"title": "elements", "type": "array", "items": {"type": "string"}}
...         ),
...     ],
...     outputs=[Property(json_schema={"title": "flow_processed_query", "type": "string"})],
... )
>>> # Defining a simple prompt
>>> REASONING_PROMPT_TEMPLATE = '''Provide your best numerical estimate for: {{user_input}}
... Your answer should be a single number.
... Do not include any units, reasoning, or extra text.'''
>>> # Defining the subflow for the map step
>>> user_input_property = Property(
...     json_schema={"title": "user_input", "type": "string"}
... )
>>> flow_processed_query_property = Property(
...     json_schema={"title": "flow_processed_query", "type": "string"}
... )
>>> start_node = StartNode(name="start", inputs=[user_input_property])
>>> end_node = EndNode(name="end", outputs=[flow_processed_query_property])
>>> llm_node = LlmNode(
...     name="reasoning llm node",
...     llm_config=llm_config,
...     prompt_template=REASONING_PROMPT_TEMPLATE,
...     inputs=[user_input_property],
...     outputs=[flow_processed_query_property],
... )
>>> inner_map_flow = Flow(
...     name="Map flow",
...     start_node=start_node,
...     nodes=[start_node, llm_node, end_node],
...     control_flow_connections=[
...         ControlFlowEdge(name="start_to_llm", from_node=start_node, to_node=llm_node),
...         ControlFlowEdge(name="llm_to_end", from_node=llm_node, to_node=end_node),
...     ],
...     data_flow_connections=[
...         DataFlowEdge(
...             name="query_edge",
...             source_node=start_node,
...             source_output="user_input",
...             destination_node=llm_node,
...             destination_input="user_input",
...         ),
...         DataFlowEdge(
...             name="search_results_edge",
...             source_node=llm_node,
...             source_output="flow_processed_query",
...             destination_node=end_node,
...             destination_input="flow_processed_query"
...         ),
...     ],
... )

```

--------------------------------

### Create a Simple Q&A Flow with StartNode and LlmNode

Source: https://oracle.github.io/agent-spec/25.4.1/api/flows

This Python example demonstrates creating a basic flow for answering user questions. It utilizes StartNode for input, LlmNode for processing the question with a prompt, and EndNode for output. Data and control flow edges connect these nodes to define the execution path and data transfer.

```python
from pyagentspec.property import Property
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.nodes import EndNode, LlmNode, StartNode

user_question_property = Property(
    json_schema=dict(
        title="user_question",
        description="The user question.",
        type="string",
    )
)
answer_property = Property(json_schema=dict(title="answer", type="string"))
start_node = StartNode(name="start", inputs=[user_question_property])
end_node = EndNode(name="end", outputs=[answer_property])
llm_node = LlmNode(
    name="llm node",
    prompt_template="Answer the user question: {{user_question}}",
    llm_config=llm_config,
)
flow = Flow(
    name="flow",
    start_node=start_node,
    nodes=[start_node, llm_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="start_to_llm", from_node=start_node, to_node=llm_node),
        ControlFlowEdge(name="llm_to_end", from_node=llm_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="query_edge",
            source_node=start_node,
            source_output="user_question",
            destination_node=llm_node,
            destination_input="user_question",
        ),
        DataFlowEdge(
            name="answer_edge",
            source_node=llm_node,
            source_output="generated_text",
            destination_node=end_node,
            destination_input="answer"
        ),
    ],
)
```

--------------------------------

### LLM Node Flow Example in Python

Source: https://oracle.github.io/agent-spec/25.4.1/agentspec/language_spec_25_4_1

Demonstrates how to construct a flow using LLM nodes, start nodes, and end nodes in Python. It defines properties, connects nodes with control and data flow edges, and specifies LLM configurations for processing prompts. This example requires pyagentspec library.

```python
from pyagentspec.property import Property
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.nodes import LlmNode, StartNode, EndNode

# Assuming llm_config is defined elsewhere and holds LLM configuration details
# For demonstration purposes, let's create a placeholder
class MockLlmConfig:
    pass
llm_config = MockLlmConfig()

country_property = Property(
    json_schema={"title": "country", "type": "string"}
)
capital_property = Property(
    json_schema={"title": "capital", "type": "string"}
)

start_node = StartNode(name="start", inputs=[country_property])
end_node = EndNode(name="end", outputs=[capital_property])

llm_node = LlmNode(
    name="simple llm node",
    llm_config=llm_config,
    prompt_template="What is the capital of {{ country }}?",
    inputs=[country_property],
    outputs=[capital_property],
)

flow = Flow(
    name="Get the country's capital flow",
    start_node=start_node,
    nodes=[start_node, llm_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="start_to_llm", from_node=start_node, to_node=llm_node),
        ControlFlowEdge(name="llm_to_end", from_node=llm_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="country_edge",
            source_node=start_node,
            source_output="country",
            destination_node=llm_node,
            destination_input="country",
        ),
        DataFlowEdge(
            name="capital_edge",
            source_node=llm_node,
            source_output="capital",
            destination_node=end_node,
            destination_input="capital"
        ),
    ],
)

print(f"Flow '{flow.name}' created successfully.")

```

--------------------------------

### Load Assistant Config and Execute with WayFlow

Source: https://oracle.github.io/agent-spec/25.4.1/howtoguides/howto_plugin

This snippet demonstrates how to load an assistant's configuration from a file (e.g., assistant_config.json) using AgentSpecLoader and then execute the assistant. It includes starting a conversation, executing it, and handling the output based on the execution status.

```python
from wayflowcore.flow import Flow as RuntimeFlow
from wayflowcore.agentspec import AgentSpecLoader

with open("assistant_config.json") as f:
    agentspec_export = f.read()

# agentspec_loader = AgentSpecLoader(plugins=[example_deserialization_plugin])
assistant: RuntimeFlow = agentspec_loader.load_yaml(agentspec_export)

inputs = {}
conversation = assistant.start_conversation(inputs)

status = conversation.execute()
if isinstance(status, FinishedStatus):
    outputs = status.output_values
    print(f"Assistant outputs: {outputs['output']}")
else:
    print(f"ERROR: Expected 'FinishedStatus', got {status.__class__.__name__}")
```

--------------------------------

### InputMessageNode Example: Rephrasing Paragraph

Source: https://oracle.github.io/agent-spec/development/agentspec/language_spec_25_4_1

This example demonstrates how to use `InputMessageNode` within a flow to capture user input, process it with an LLM, and provide a rephrased output. It defines the structure of a flow including start, prompt, input, LLM, and output nodes, along with control and data flow connections.

```python
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.nodes import StartNode, EndNode, InputMessageNode, OutputMessageNode, LlmNode
from pyagentspec.property import StringProperty

start_node = StartNode(name="start")
prompt_node = OutputMessageNode(name="ask_input", message="What is the paragraph you want to rephrase?")
input_node = InputMessageNode(name="user_input", outputs=[StringProperty(title="user_input")])
llm_node = LlmNode(
    name="rephrase",
    llm_config=llm_config,
    prompt_template="Rephrase {{user_input}}",
    outputs=[StringProperty(title="rephrased_user_input")],
)
output_node = OutputMessageNode(name="ask_input", message="{{rephrased_user_input}}")
end_node = EndNode(name="end")

flow = Flow(
    name="rephrase_paragraph_flow",
    start_node=start_node,
    nodes=[start_node, prompt_node, input_node, llm_node, output_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="ce1", from_node=start_node, to_node=prompt_node),
        ControlFlowEdge(name="ce2", from_node=prompt_node, to_node=input_node),
        ControlFlowEdge(name="ce3", from_node=input_node, to_node=llm_node),
        ControlFlowEdge(name="ce4", from_node=llm_node, to_node=output_node),
        ControlFlowEdge(name="ce5", from_node=output_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="de1",
            source_node=input_node,
            source_output="user_input",
            destination_node=llm_node,
            destination_input="user_input",
        ),
        DataFlowEdge(
            name="de2",
            source_node=llm_node,
            source_output="rephrased_user_input",
            destination_node=output_node,
            destination_input="rephrased_user_input",
        ),
    ]
)
```

--------------------------------

### Example: Constructing a Rephrase Paragraph Flow

Source: https://oracle.github.io/agent-spec/development/agentspec/language_spec_25_4_1

This Python code demonstrates how to build a conversational flow for rephrasing a user-provided paragraph using pyagentspec. It defines nodes for starting, prompting, input, LLM processing, output, and ending, along with control and data flow connections between them. This example requires pyagentspec library components.

```python
from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
from pyagentspec.flows.flow import Flow
from pyagentspec.flows.nodes import StartNode, EndNode, InputMessageNode, OutputMessageNode, LlmNode
from pyagentspec.property import StringProperty

# Assume llm_config is defined elsewhere and configured for an LLM
# For example:
# class MockLlmConfig:
#     def __init__(self):
#         pass
# llm_config = MockLlmConfig()

start_node = StartNode(name="start")
prompt_node = OutputMessageNode(name="ask_input", message="What is the paragraph you want to rephrase?")
input_node = InputMessageNode(name="user_input", outputs=[StringProperty(title="user_input")])
llm_node = LlmNode(
    name="rephrase",
    # llm_config=llm_config, # Ensure llm_config is properly instantiated
    prompt_template="Rephrase {{user_input}}",
    outputs=[StringProperty(title="rephrased_user_input")],
)
output_node = OutputMessageNode(name="display_rephrased", message="{{rephrased_user_input}}")
end_node = EndNode(name="end")

flow = Flow(
    name="rephrase_paragraph_flow",
    start_node=start_node,
    nodes=[start_node, prompt_node, input_node, llm_node, output_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="ce1", from_node=start_node, to_node=prompt_node),
        ControlFlowEdge(name="ce2", from_node=prompt_node, to_node=input_node),
        ControlFlowEdge(name="ce3", from_node=input_node, to_node=llm_node),
        ControlFlowEdge(name="ce4", from_node=llm_node, to_node=output_node),
        ControlFlowEdge(name="ce5", from_node=output_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="de1",
            source_node=input_node,
            source_output="user_input",
            destination_node=llm_node,
            destination_input="user_input",
        ),
        DataFlowEdge(
            name="de2",
            source_node=llm_node,
            source_output="rephrased_user_input",
            destination_node=output_node,
            destination_input="rephrased_user_input",
        ),
    ]
)
```

--------------------------------

### Configure and Define Agent with LLM and Tools

Source: https://oracle.github.io/agent-spec/development/howtoguides/howto_agent_with_remote_tools

This Python snippet configures a language model using VLLM and then defines an `Agent` object. The agent is initialized with a name, LLM configuration, a list of previously defined tools, and a detailed system prompt. The system prompt includes placeholders for the agent's title, description, workflow information, topics, special instructions, and formatting guidelines, enabling dynamic agent behavior. The agent's inputs are also specified.

```python
from pyagentspec.llms.vllmconfig import VllmConfig

llm_config = VllmConfig(
    name="Vllm model",
    url="vllm_url",
    model_id="model_id",
)

from pyagentspec.agent import Agent

system_prompt = """You are a helpful agent. Your official title is: {{agent_title}}.
The following statement describes your responsibilities:
"{{agent_description}}".

You are part of the workflow {{workflow_title}} within the company.
The following is a quick description of the workflow:
"{{workflow_description}}".

Your tasks are related to the following topics with their special instructions:
{{topics}}

Here are some extra special instructions:
{{special_instructions}}

Your answer is intended to be customer-facing, be sure to be professional in your response.
Do not invent answers or information.

{{format_instructions}}

{{context}}
"""

agent = Agent(
    name="Benefits Advisor",
    llm_config=llm_config,
    tools=tools,
    system_prompt=system_prompt,
    inputs=[
        agent_title_property,
        agent_description_property,
        workflow_title_property,
        workflow_description_property,
        topics_property,
        format_instructions_property,
        special_instructions_property,
        context_property,
    ],
)
```

--------------------------------

### Get User Information Flow

Source: https://oracle.github.io/agent-spec/development/howtoguides/howto_parallelflownode

Defines a flow for retrieving user information. It includes input and output schemas for user details. This flow acts as a starting point for related processes.

```yaml
d2f33b8f-eb0f-4952-94ed-5eb84c8381f6:
  component_type: EndNode
  id: d2f33b8f-eb0f-4952-94ed-5eb84c8381f6
  name: get_user_information_step_flow_start
  description: null
  metadata: {}
  inputs:
  - title: user_info
    additionalProperties:
      type: string
    properties: {}
    type: object
  outputs:
  - title: user_info
    additionalProperties:
      type: string
    properties: {}
    type: object
  branches: []
  branch_name: next
```

--------------------------------

### Define Agent with System Prompt and Tools

Source: https://oracle.github.io/agent-spec/25.4.1/howtoguides/howto_agent_with_remote_tools

This Python code defines an `Agent` object named 'Benefits Advisor'. It integrates the previously defined `llm_config` and `tools`. The `system_prompt` provides detailed instructions and context for the agent's behavior, including its title, description, workflow information, task-specific instructions, and formatting guidelines. The agent's inputs are also specified, which are necessary for populating the system prompt variables.

```python
from pyagentspec.agent import Agent

system_prompt = """You are a helpful agent. Your official title is: {{agent_title}}.
The following statement describes your responsibilities:
"{{agent_description}}".

You are part of the workflow {{workflow_title}} within the company.
The following is a quick description of the workflow:
"{{workflow_description}}".

Your tasks are related to the following topics with their special instructions:
{{topics}}

Here are some extra special instructions:
{{special_instructions}}

Your answer is intended to be customer-facing, be sure to be professional in your response.
Do not invent answers or information.

{{format_instructions}}

{{context}}
"""

agent = Agent(
    name="Benefits Advisor",
    llm_config=llm_config,
    tools=tools,
    system_prompt=system_prompt,
    inputs=[
        agent_title_property,
        agent_description_property,
        workflow_title_property,
        workflow_description_property,
        topics_property,
        format_instructions_property,
        special_instructions_property,
        context_property,
    ],
)
```

--------------------------------

### Define Device Agent with System Prompt

Source: https://oracle.github.io/agent-spec/development/howtoguides/howto_orchestrator_agent

Defines the device agent, an expert in Oracle devices setup. It specifies the agent's name, description, LLM configuration, and a system prompt to guide its interactions and expertise in electronic devices.

```python
device_agent = Agent(
161    name="Device Agent",
162    description="Expert in Oracle devices setup",
163    llm_config=llm_config,
164    system_prompt="""You are an expert assistant, part of the Oracle IT support assistant.
165Your domain of expertise is electronic devices.
166
167Please assist the user in solving his problem.
168
169
170Here''s a summary of the ongoing conversation:
171
172{{conversation_summary}}
173
174
175When the user thinks that the problem is solved, or if you do not know how to
176solve the problem, just submit and exit. Do not mention to the user that you
177are submitting, just thank the user.
178
179
180You should provide as an output a summary of the past conversation you had with
181the user. It should be a short summary, 2 sentences at most. Do NOT submit the
182conversation summary until the user says that the problem is solved.""",
183    inputs=[conversation_summary_property],
184    outputs=[conversation_summary_property],
185)
```

--------------------------------

### Define Agent with System Prompt and Tools (Python)

Source: https://oracle.github.io/agent-spec/25.4.1/howtoguides/howto_agent_with_remote_tools

This Python code defines an agent using the `pyagentspec` library. It sets up a detailed system prompt with placeholder variables for dynamic content and specifies the Large Language Model (LLM) configuration and available tools. The agent is initialized with a name, LLM configuration, tools, system prompt, and a list of input properties.

```python
from pyagentspec.agent import Agent

system_prompt = """You are a helpful agent. Your official title is: {{agent_title}}.
The following statement describes your responsibilities:
"{{agent_description}}".

You are part of the workflow {{workflow_title}} within the company.
The following is a quick description of the workflow:
"{{workflow_description}}".

Your tasks are related to the following topics with their special instructions:
{{topics}}

Here are some extra special instructions:
{{special_instructions}}

Your answer is intended to be customer-facing, be sure to be professional in your response.
Do not invent answers or information.

{{format_instructions}}

{{context}}
"""

agent = Agent(
    name="Benefits Advisor",
    llm_config=llm_config,
    tools=tools,
    system_prompt=system_prompt,
    inputs=[
        agent_title_property,
        agent_description_property,
        workflow_title_property,
        workflow_description_property,
        topics_property,
        format_instructions_property,
        special_instructions_property,
        context_property,
    ],
)

```

--------------------------------

### Calculator Tool API POST Request Example

Source: https://oracle.github.io/agent-spec/development/howtoguides/howto_agent_with_remote_tools

Demonstrates how to make a POST request to the Calculator tool's endpoint. It includes the tool's URL, HTTP method, and a JSON data payload containing the 'problem' to be solved. This is a standard way for agents to interact with external tools.

```json
{
  "url": "http://127.0.0.1:HOST_PORT/calculator",
  "http_method": "POST",
  "api_spec_uri": null,
  "data": {
    "problem": "{{problem}}"
  },
  "query_params": {},
  "headers": {}
}
```

--------------------------------

### Create Map Node for List Processing - Python

Source: https://oracle.github.io/agent-spec/25.4.1/api/flows

Illustrates the setup of a MapNode in pyagentspec, designed to execute a subflow on each element of an input list. This example defines properties and nodes necessary for a MapNode that calculates the square of numbers in a list, intended for use in L2-norm computation.

```python
>>> from pyagentspec.property import Property
>>> from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
>>> from pyagentspec.flows.flow import Flow
>>> from pyagentspec.flows.nodes import EndNode, StartNode, MapNode, ToolNode
>>> from pyagentspec.tools import ServerTool
>>> x_property = Property(json_schema={"title": "x", "type": "number"})
>>> x_square_property = Property(
...     json_schema={"title": "x_square", "type": "number"}
... )
>>> square_tool = ServerTool(
```

--------------------------------

### Create a Simple Flow with LLMNode (Python)

Source: https://oracle.github.io/agent-spec/development/agentspec/language_spec_25_4_1

This Python example demonstrates how to construct a 'Flow' object using components from the pyagentspec library. It includes defining start, end, and LLM nodes, along with control and data flow connections to orchestrate a sequence of operations, such as processing a prompt through an LLM.

```python
>>> from pyagentspec.property import Property
>>> from pyagentspec.flows.flow import Flow
>>> from pyagentspec.flows.edges import ControlFlowEdge, DataFlowEdge
>>> from pyagentspec.flows.nodes import LlmNode, StartNode, EndNode
>>> prompt_property = Property(
...     json_schema={"title": "prompt", "type": "string"}
... )
>>> llm_output_property = Property(
...     json_schema={"title": "llm_output", "type": "string"}
... )
>>> start_node = StartNode(name="start", inputs=[prompt_property])
>>> end_node = EndNode(name="end", outputs=[llm_output_property])
>>> llm_node = LlmNode(
...     name="simple llm node",
...     llm_config=llm_config,
...     prompt_template="{{prompt}}",
...     inputs=[prompt_property],
...     outputs=[llm_output_property],
... )
>>> flow = Flow(
...     name="Simple prompting flow",
...     start_node=start_node,
...     nodes=[start_node, llm_node, end_node],
...     control_flow_connections=[
...         ControlFlowEdge(name="start_to_llm", from_node=start_node, to_node=llm_node),
...         ControlFlowEdge(name="llm_to_end", from_node=llm_node, to_node=end_node),
...     ],
...     data_flow_connections=[
...         DataFlowEdge(
...             name="prompt_edge",
...             source_node=start_node,
...             source_output="prompt",
...             destination_node=llm_node,
...             destination_input="prompt",
...         ),
...         DataFlowEdge(
...             name="llm_output_edge",
...             source_node=llm_node,
...             source_output="llm_output",
...             destination_node=end_node,
...             destination_input="llm_output"
...         ),
...     ],
... )
```

--------------------------------

### Define Basic Python Tools and Registry

Source: https://oracle.github.io/agent-spec/25.4.1/howtoguides/howto_execute_agentspec_across_frameworks

Defines simple Python functions 'hello_world' and 'rag_tool' to be used as agent tools. It also creates a 'tool_registry' dictionary mapping tool names to their respective functions, essential for agent frameworks.

```python
from typing import List


def hello_world() -> None:
    """Prints 'Hello world!'"""
    print("Hello world!")
    return None


def rag_tool(query: str) -> List[str]:
    """Search and return the list of results"""
    return ["result 1", "result 2"]

tool_registry = {
    "rag_tool": rag_tool,
    "hello_world_tool": hello_world,
}
```

--------------------------------

### Build Agent with MCP ToolBox

Source: https://oracle.github.io/agent-spec/development/howtoguides/howto_mcp

Constructs an Agent instance, connecting it to MCP tools via an MCPToolBox. It specifies the LLM configuration, a system prompt, and the toolboxes to be used by the agent.

```python
mcp_client = SSETransport(name="MCP Client", url=mcp_server_url)

payslip_mcptoolbox = MCPToolBox(
    name="Payslip MCP ToolBox",
    client_transport=mcp_client
)
agent = Agent(
    name="Agent using MCP",
    llm_config=llm_config,
    system_prompt="Use tools at your disposal to assist the user.",
    toolboxes=[payslip_mcptoolbox],
)
```

--------------------------------

### Define Start Node for L2 Normalization

Source: https://oracle.github.io/agent-spec/25.4.1/agentspec/language_spec_25_4_1

Defines the starting node of the L2 normalization flow. It accepts 'x_list' as input and is named 'start'.

```python
start_node = StartNode(name="start", inputs=[list_of_x_property])
```

--------------------------------

### Instantiate Agent Class in Python

Source: https://oracle.github.io/agent-spec/25.4.1/api/agent

This snippet demonstrates how to instantiate the Agent class from the pyagentspec library. It shows the creation of an agent with a specific name, system prompt, and input properties, utilizing an LLM configuration. The example highlights the flexibility in defining agent expertise through properties.

```python
from pyagentspec.agent import Agent
from pyagentspec.property import Property

expertise_property=Property(
    json_schema={"title": "domain_of_expertise", "type": "string"}
)
system_prompt = '''You are an expert in {{domain_of_expertise}}.
Please help the users with their requests.'''

agent = Agent(
    name="Adaptive expert agent",
    system_prompt=system_prompt,
    llm_config=llm_config,
    inputs=[expertise_property],
)
```
Tokens:
Raw