Open Agent Specification

https://oracle.github.io/agent-spec/26.1.0/
Admin
A portable, platform-agnostic configuration language for defining agentic systems including agents...
Tokens:197,382
Snippets:1,626
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete AgentSpec Setup and Conversational Execution

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

This comprehensive example demonstrates the full setup for running an AgentSpec assistant with WayFlow. It includes defining tools, loading the AgentSpec configuration, and executing a conversational flow similar to the first example.

```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)
```

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

### Create a simple prompting Flow

Source: https://oracle.github.io/agent-spec/26.1.0/misc/reference_sheet.html

This example demonstrates a basic prompting flow using LLMNode, connecting start, LLM, and end nodes with control and data flow edges.

```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 a Simple Prompting Flow

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

This example demonstrates how to construct a basic flow with start, LLM, and end nodes, including control and data flow connections. Ensure all necessary classes like Property, Flow, ControlFlowEdge, DataFlowEdge, LlmNode, StartNode, and EndNode are imported.

```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"
...         ),
...     ],
... )
```

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

### Python Tool Registry Example

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

Defines example Python functions for tools and registers them. This setup is necessary for agent frameworks to find and execute custom tools.

```python
# Copyright © 2025 Oracle and/or its affiliates.
#
# This software is under the Apache License 2.0
# (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
# (UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.

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,
}

```

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

### Install PyAgentSpec and WayFlowCore

Source: https://oracle.github.io/agent-spec/26.1.0/adapters/wayflow/index.html

Set up your Python environment and install the necessary packages. Python 3.10 or newer is required.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install pyagentspec wayflowcore

```

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

### Execute Assistant and Get Output

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

Starts a conversation with the loaded `assistant`, executes it, and prints the final output. Handles cases where the execution status is not `FinishedStatus`.

```python
from wayflowcore.executors.executionstatus import FinishedStatus
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__}")

# Assistant outputs: 551

```

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

### Create and Execute a Flow with Parallel Execution

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

Construct a Flow object, defining start and end nodes, parallel nodes, and control/data flow connections. This example demonstrates setting up a flow that includes parallel processing.

```python
from pyagentspec.flows.flow import Flow

start_node = StartNode(name="start_node", inputs=[username_property])
end_node = EndNode(name="end_node")
flow = Flow(
    name="marketing_message_flow",
    start_node=start_node,
    nodes=[parallel_flow_node, prepare_marketing_message_node, output_message_node, start_node, end_node],
    control_flow_connections=[
        ControlFlowEdge(name="cfe1", from_node=start_node, to_node=parallel_flow_node),
        ControlFlowEdge(name="cfe2", from_node=parallel_flow_node, to_node=prepare_marketing_message_node),
        ControlFlowEdge(name="cfe3", from_node=prepare_marketing_message_node, to_node=output_message_node),
        ControlFlowEdge(name="cfe4", from_node=output_message_node, to_node=end_node),
    ],
    data_flow_connections=[
        DataFlowEdge(
            name="dfe_username",
            source_node=start_node, source_output="username",
            destination_node=parallel_flow_node, destination_input="username",
        )
    ] + [
        DataFlowEdge(
            name="dfe_" + property_.title,
            source_node=parallel_flow_node, source_output=property_.title,
            destination_node=prepare_marketing_message_node, destination_input=property_.title,
        )
        for property_ in [current_time_property, user_info_property, user_purchases_property, items_on_sale_property]
    ]
)
```

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

### Constructing a Rephrase Paragraph Flow

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

This example demonstrates how to build a complete agent flow for rephrasing user input. It includes setting up start, prompt, input, LLM, output, and end nodes, along with defining both control and data flow connections between them.

```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",
...         ),
...     ]
... )
```

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

### Create a BranchingNode Flow Example

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

Demonstrates the creation of a flow with a BranchingNode to control access based on a password. This example sets up an agent to ask for a password and then uses a BranchingNode to direct the flow to either an 'access granted' or 'access denied' end node.

```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
>>> CORRECT_PASSWORD_BRANCH = "PASSWORD_OK"
>>> password_property = Property(
...     json_schema={"title": "password", "type": "string"}
... )
>>> agent = Agent(
...     name="User input agent",
...     llm_config=llm_config,
...     system_prompt=(
...         "Your task is to ask the password to the user. "
...         "Once you get it, submit it and end."
...     ),
...     outputs=[password_property],
... )
>>> start_node = StartNode(name="start")
>>> access_granted_end_node = EndNode(
...     name="access granted end", branch_name="ACCESS_GRANTED"
... )
>>> access_denied_end_node = EndNode(
...     name="access denied end", branch_name="ACCESS_DENIED"
... )
>>> branching_node = BranchingNode(
...     name="password check",
...     mapping={"123456": CORRECT_PASSWORD_BRANCH},
...     inputs=[password_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,
...         access_granted_end_node,
...         access_denied_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_access_granted",
...             from_node=branching_node,
...             from_branch=CORRECT_PASSWORD_BRANCH,
...             to_node=access_granted_end_node,
...         ),
...         ControlFlowEdge(
...             name="branching_to_access_denied",
...             from_node=branching_node,
...             from_branch=BranchingNode.DEFAULT_BRANCH,
...             to_node=access_denied_end_node,
...         ),
...     ],
...     data_flow_connections=[
...         DataFlowEdge(
...             name="password_edge",
...             source_node=agent_node,
...             source_output="password",
...             destination_node=branching_node,
...             destination_input="password",
...         ),
...     ],
... )

```

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

### Install WayFlow Core

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

Install the wayflowcore package to use its Agent Spec adapter. Ensure you specify the version for compatibility.

```bash
pip install "wayflowcore==26.1.0"
```

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

### Create and Start a Simple MCP Server

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

This Python code defines and starts a basic MCP server using FastMCP, exposing 'get_user_session' and 'get_payslips' tools. It's intended to be run in a separate Python process.

```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

```

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

### Install PyAgentSpec with AutoGen Extension

Source: https://oracle.github.io/agent-spec/26.1.0/adapters/autogen/index.html

Set up your Python environment and install the necessary packages. Ensure you are using Python 3.10 to 3.12.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install "pyagentspec[autogen]"
```

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

### Configure Agent with LLM, Tools, and Inputs

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_agents.html

Set up an agent with LLM configuration, define server tools with input/output properties, and specify agent inputs. This example shows how to integrate these components for a helpful writing assistant.

```python
from pyagentspec.agent import Agent
from pyagentspec.llms import VllmConfig
from pyagentspec.property import ListProperty, StringProperty
from pyagentspec.serialization import AgentSpecSerializer
from pyagentspec.tools import ServerTool

llm_config = VllmConfig(
    name="vllm-llama-4-maverick",
    model_id="llama-4-maverick",
    url="http://url.to.my.vllm.server/llama4mav",
)

tools = [
    ServerTool(
        name="get_synonyms",
        description="Given a word, return the list of synonyms according to the vocabulary",
        inputs=[StringProperty(title="word")],
        outputs=[ListProperty(title="synonyms", item_type=StringProperty(title="word"))]
    ),
    ServerTool(
        name="pretty_formatting",
        description="Given a paragraph, format the paragraph to fix spaces, newlines, indentation, etc.",
        inputs=[StringProperty(title="paragraph")],
        outputs=[StringProperty(title="formatted_paragraph")]
    ),
]

agent = Agent(
    name="Helpful agent with username and tools",
    llm_config=llm_config,
    system_prompt="""Your a helpful writing assistant. Answer the user's questions about article writing.
Make sure to welcome the user first, their name is {{user_name}}, but keep it short""",
    tools=tools,
    inputs=[StringProperty(title="user_name")]
)

serialized_assistant = AgentSpecSerializer().to_json(agent)

```

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

### Example Agent Configuration

Source: https://oracle.github.io/agent-spec/26.1.0/misc/reference_sheet.html

This JSON configuration demonstrates how to set up an Agent with a specific LLM, system prompt, and input/output definitions. It includes details for a `VllmConfig`.

```json
{
  "id": "expert_agent_id",
  "name": "Adaptive expert agent",
  "description": null,
  "metadata": {},
  "inputs": [
    {
      "title": "domain_of_expertise",
      "type": "string"
    }
  ],
  "outputs": [],
  "llm_config": {
    "id": "llama_model_id",
    "name": "Llama 3.1 8B instruct",
    "description": null,
    "metadata": {},
    "default_generation_parameters": {},
    "url": "url.of.my.llm.deployment:12345",
    "model_id": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "component_type": "VllmConfig"
  },
  "system_prompt": "You are an expert in {{domain_of_expertise}}. Please help the users with their requests.",
  "tools": [],
  "human_in_the_loop": true,
  "component_type": "Agent",
  "agentspec_version": "26.1.0"
}

```

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

### Agent Class Initialization

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

Demonstrates how to initialize an Agent instance with its required parameters like name, system prompt, and LLM configuration, along with optional parameters for inputs, outputs, and tools.

```APIDOC
## Agent Class

### Description
An agent is a component that can do several rounds of conversation to solve a task. It can be executed by itself, or be executed in a flow using an AgentNode.

### Parameters
* **id** (_str_) – A unique identifier for this Component
* **name** (_str_) – Name of this Component
* **description** (_str_ or _None_) – Optional description of this Component
* **metadata** (_Dict[str, Any] or None_) – Optional, additional metadata related to this Component
* **min_agentspec_version** (_AgentSpecVersionEnum_) – 
* **max_agentspec_version** (_AgentSpecVersionEnum_) – 
* **inputs** (_List[Property] or None_) – List of inputs accepted by this component
* **outputs** (_List[Property] or None_) – List of outputs exposed by this component
* **llm_config** (_LlmConfig_) – Configuration of the LLM to use for this Agent
* **system_prompt** (_str_) – Initial system prompt used for the initialization of the agent’s context
* **tools** (_List[Tool]_) – List of tools that the agent can use to fulfil user requests
* **toolboxes** (_List[ToolBox]_) – List of toolboxes that are passed to the agent.
* **human_in_the_loop** (_bool_) – Flag that determines if the Agent can request input from the user.

### Example
```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],
... )
```
```

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

### Define Data Flow Edge

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_flow_with_conditional_branches.html

Establish a DataFlowEdge to pass data between nodes. This example shows passing the 'user_request' from the start node to the generate code node.

```python
data_flow_edges = [
    DataFlowEdge(
        name="start_to_generate_code_user_request_data_edge",
        source_node=start_node,
        source_output="user_request",

```

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

### Configure LLM and Agent with Tools

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

Set up the LLM configuration, including the URL and model ID, and then instantiate the Agent with the defined tools and a system prompt.

```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,
    ],
)

```

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

### Instantiate an Agent with Expertise

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

Demonstrates how to create an Agent instance, defining its name, system prompt with a placeholder for expertise, and specifying inputs.

```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 R}}.
Please help the users with their requests.'''
agent = Agent(
    name="Adaptive expert agent",
    system_prompt=system_prompt,
    llm_config=llm_config,
    inputs=[expertise_property],
)
```

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

### Define an Agent with Tools and Outputs

Source: https://oracle.github.io/agent-spec/26.1.0/agentspec/language_spec_26_1_0.html

This example demonstrates how to define an Agent with a name, LLM configuration, system prompt, tools, and outputs. It's useful for creating agents that can perform specific tasks using provided tools.

```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
>>> 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],
... )
```

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

### Define Control Flow Edges

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_flow_with_conditional_branches.html

Connect nodes in the flow using ControlFlowEdge. This example shows edges for starting the flow, generating code, reviewing code, checking readiness, and branching based on the review outcome.

```python
control_flow_edges = [
    ControlFlowEdge(
        name="start_to_generate_code_control_edge",
        from_node=start_node,
        to_node=generate_code_node,
    ),
    ControlFlowEdge(
        name="generate_code_to_review_control_edge",
        from_node=generate_code_node,
        to_node=review_code_node,
    ),
    ControlFlowEdge(
        name="review_to_is_code_ready_decision_control_edge",
        from_node=review_code_node,
        to_node=is_code_ready_decision_node,
    ),
    ControlFlowEdge(
        name="is_code_ready_decision_to_is_code_ready_branching_control_edge",
        from_node=is_code_ready_decision_node,
        to_node=is_code_ready_branching_node,
    ),
    ControlFlowEdge(
        name="is_code_ready_branching_to_end_control_edge",
        from_node=is_code_ready_branching_node,
        from_branch="yes",
        to_node=end_node,
    ),
    ControlFlowEdge(
        name="is_code_ready_branching_to_generate_code_control_edge",
        from_node=is_code_ready_branching_node,
        from_branch="no",
        to_node=generate_code_node,
    ),
]
```

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

### Load and Execute Assistant Configuration

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

Demonstrates loading an assistant configuration from a file and executing it. Ensure the AgentSpecLoader is configured with necessary deserialization plugins.

```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)
```

```python
from wayflowcore.executors.executionstatus import FinishedStatus
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__}")
```

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

### Define an Account Expert Agent

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

Configures an expert agent specialized in Oracle account setup. It uses a provided LLM configuration and a system prompt to guide its responses, focusing on assisting users with account-related issues and summarizing the conversation.

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

conversation_summary_property = StringProperty(title="conversation_summary")

Agent(
    name="Account Agent",
    description="Expert in Oracle Account setup",
    llm_config=llm_config,
    system_prompt="""You are an expert assistant, part of the Oracle IT support assistant.
Your domain of expertise is Oracle account setup.

Please assist the user in solving his problem.


Here''s a summary of the ongoing conversation:

{{conversation_summary}}


When the user thinks that the problem is solved, or if you do not know how to
solve the problem, just submit and exit. Do not mention to the user that you
are submitting, just thank the user.


You should provide as an output a summary of the past conversation you had with
the user. It should be a short summary, 2 sentences at most. Do NOT submit the
conversation summary until the user says that the problem is solved.""",
    inputs=[conversation_summary_property],
    outputs=[conversation_summary_property],
)
```

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

### Configure FastAPI Endpoint for AG-UI Agent Spec

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html

This Python code sets up a FastAPI application to expose AG-UI endpoints for Agent Spec. It automatically detects installed runtimes (LangGraph, Wayflow) and mounts the appropriate backend tool rendering endpoints. Ensure necessary libraries like `langgraph` or `wayflowcore` are installed for full functionality. This setup is for development and requires additional security measures for production.

```python
import os
import importlib.util
import logging
from fastapi import APIRouter, FastAPI

from ag_ui_agentspec.agent import AgentSpecAgent
from ag_ui_agentspec.endpoint import add_agentspec_fastapi_endpoint

logger = logging.getLogger(__name__)
router = APIRouter()


def _is_available(module_name: str) -> bool:
    return importlib.util.find_spec(module_name) is not None


def _mount(router: APIRouter):
    # LangGraph
    if _is_available("langgraph"):
        add_agentspec_fastapi_endpoint(
            app=router,
            agentspec_agent=AgentSpecAgent(
                backend_tool_rendering_agent_json,
                runtime="langgraph",
                tool_registry=tool_registry,
            ),
            path="/langgraph/backend_tool_rendering",
        )
    else:
        logger.info("LangGraph not available. Skipping LangGraph endpoints.")

    # Wayflow
    # The comment mentioned 'wayflowcore' specifically
    if _is_available("wayflowcore"):
        add_agentspec_fastapi_endpoint(
            app=router,
            agentspec_agent=AgentSpecAgent(
                backend_tool_rendering_agent_json,
                runtime="wayflow",
                tool_registry=tool_registry,
            ),
            path="/wayflow/backend_tool_rendering",
        )
    else:
        logger.info("Wayflow (wayflowcore) not available. Skipping Wayflow endpoints.")

# Create the Web App

app = FastAPI(title="Agent-Spec × AG-UI Examples")
_mount(router)
app.include_router(router)
port = int(os.getenv("PORT", "9003"))
# if __name__=="__main__":
#     import uvicorn
#     uvicorn.run("server:app", host="0.0.0.0", port=port, reload=True)

```

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

### Create a Basic Agent

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_agents.html

Instantiate an Agent with a name, LLM configuration, and a system prompt. The system prompt instructs the agent on its role and behavior.

```python
from pyagentspec.agent import Agent

agent = Agent(
    name="Helpful agent",
    llm_config=llm_config,
    system_prompt="""Your a helpful writing assistant. Answer the user's questions about article writing.
Make sure to welcome the user first, but keep it short""",
)
```

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

### Define a Language Detection Flow

Source: https://oracle.github.io/agent-spec/26.1.0/agentspec/language_spec_26_1_0.html

This example demonstrates how to construct a flow for detecting user language. It includes setting up an agent, defining start and end nodes for different languages, and establishing control and data flow connections between them. Use this to create automated language processing pipelines.

```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
>>> 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"]
... )
>>> spanish_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",
...         ),
...     ],
... )

```

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

### Create a Search Agent Flow with AgentNode

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

This example demonstrates how to construct a flow using AgentNode, StartNode, and EndNode. It includes defining properties, tools, agents, and connecting nodes with control and data flow edges.

```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
>>> 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"
...         ),
...     ],
... )
```

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

### pyagentspec.flows.nodes.StartNode

Source: https://oracle.github.io/agent-spec/26.1.0/api/index.html

Start nodes denote the start of the execution of a flow.

```APIDOC
## Class: pyagentspec.flows.nodes.StartNode

### Description
Start nodes denote the start of the execution of a flow.

### Usage
```python
from pyagentspec.flows.nodes import StartNode

# Example usage (conceptual)
# start_node = StartNode()
```
```

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

### Define Agent with Custom Instructions and Tools

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

Instantiate an Agent with a name, LLM configuration, tools, a detailed system prompt, and input properties. The system prompt uses placeholders for dynamic content and defines the agent's responsibilities and instructions.

```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,
    ],
)

```

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

### Install AG-UI Agent Spec Integration

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_ag_ui.html

Clone the AG-UI repository and install the Agent Spec Python integration from source. This command installs pyagentspec and its adapters for various frameworks.

```bash
git clone git@github.com:ag-ui-protocol/ag-ui.git
cd ag-ui/integrations/agent-spec/python
pip install -e .
```

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

### Define Start and End Nodes

Source: https://oracle.github.io/agent-spec/26.1.0/howtoguides/howto_flow_with_conditional_branches.html

Define the start and end points of your flow using StartNode and EndNode. Specify input properties for the start node and output properties for the end node.

```python
start_node = StartNode(
    name="Start node",
    inputs=[user_request_property],
)

end_node = EndNode(
    name="End node",
    outputs=[code_property],
)
```

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

### Install PyAgentSpec

Source: https://oracle.github.io/agent-spec/26.1.0/docs_home.html

Use this command to install the pyagentspec library. Ensure you are using Python 3.10+.

```bash
pip install "pyagentspec==26.1.0"
```

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

### Build Agent with MCP ToolBox

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

Create an MCP client using SSETransport and initialize an MCPToolBox. Equip an Agent with the toolbox and a system prompt.

```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],
)
```

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

### Install AutoGen Extension for pyagentspec

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

Installs the pyagentspec library with the 'autogen' extension to enable its use with AutoGen.

```bash
pip install "pyagentspec[autogen]"

```

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

### Create an Adaptive Expert Agent with PyAgentSpec

Source: https://oracle.github.io/agent-spec/26.1.0/docs_home.html

This example demonstrates how to define an agent using PyAgentSpec, configuring its LLM, expertise property, and system prompt.

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

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

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],
)
```

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

### Define a Flow with LlmNode

Source: https://oracle.github.io/agent-spec/26.1.0/agentspec/language_spec_26_1_0.html

Example of creating a Flow with a StartNode, LlmNode, and EndNode. Demonstrates setting up control and data flow connections between nodes. Ensure llm_config is properly defined.

```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
>>> 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"
...         ),
...     ],
... )
```
Tokens:
Raw