Skip to content

Commit ea02cc7

Browse files
paul-cayetpaul-cayet
authored
docs: add guide on how to use AG-UI with agent spec
1 parent 078600a commit ea02cc7

File tree

7 files changed

+354
-0
lines changed

7 files changed

+354
-0
lines changed

‎docs/pyagentspec/source/_static/howto/ag_ui_integration.jpg‎

286 KB
Loading

‎docs/pyagentspec/source/_static/howto/ag_ui_screenshot.png‎

335 KB
Loading

‎docs/pyagentspec/source/agentspec_config_examples/howto_ag_ui.json‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
{
2+
"component_type": "Agent",
3+
"id": "67ae0b68-53ab-458c-b8b7-43009ab81e34",
4+
"name": "my_agent",
5+
"description": null,
6+
"metadata": {},
7+
"inputs": [],
8+
"outputs": [],
9+
"llm_config": {
10+
"component_type": "OpenAiCompatibleConfig",
11+
"id": "c7dc111f-5c25-4aa0-8329-f6d44d578780",
12+
"name": "my_llm",
13+
"description": null,
14+
"metadata": {},
15+
"default_generation_parameters": null,
16+
"url": "https://api.openai.com/v1",
17+
"model_id": "gpt-4o"
18+
},
19+
"system_prompt": "Based on the weather forecaset result and the user input, write a response to the user",
20+
"tools": [
21+
{
22+
"component_type": "ServerTool",
23+
"id": "cd54932c-bda9-4021-aa12-110276bb86f3",
24+
"name": "get_weather",
25+
"description": "Get the weather for a given location.",
26+
"metadata": {},
27+
"inputs": [
28+
{
29+
"description": "The location to get the weather forecast. Must be a city/town name.",
30+
"title": "location",
31+
"type": "string"
32+
}
33+
],
34+
"outputs": [
35+
{
36+
"title": "weather_result",
37+
"type": "string"
38+
}
39+
]
40+
}
41+
],
42+
"agentspec_version": "25.4.1"
43+
}

‎docs/pyagentspec/source/agentspec_config_examples/howto_ag_ui.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
component_type: Agent
2+
id: 67ae0b68-53ab-458c-b8b7-43009ab81e34
3+
name: my_agent
4+
description: null
5+
metadata: {}
6+
inputs: []
7+
outputs: []
8+
llm_config:
9+
component_type: OpenAiCompatibleConfig
10+
id: c7dc111f-5c25-4aa0-8329-f6d44d578780
11+
name: my_llm
12+
description: null
13+
metadata: {}
14+
default_generation_parameters: null
15+
url: https://api.openai.com/v1
16+
model_id: gpt-4o
17+
system_prompt: Based on the weather forecaset result and the user input, write a response
18+
to the user
19+
tools:
20+
- component_type: ServerTool
21+
id: cd54932c-bda9-4021-aa12-110276bb86f3
22+
name: get_weather
23+
description: Get the weather for a given location.
24+
metadata: {}
25+
inputs:
26+
- description: The location to get the weather forecast. Must be a city/town name.
27+
title: location
28+
type: string
29+
outputs:
30+
- title: weather_result
31+
type: string
32+
agentspec_version: 25.4.1

‎docs/pyagentspec/source/code_examples/howto_ag_ui.py‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Copyright © 2025 Oracle and/or its affiliates.
2+
#
3+
# This software is under the Apache License 2.0
4+
# (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License
5+
# (UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.
6+
7+
# isort:skip_file
8+
# fmt: off
9+
# mypy: ignore-errors
10+
# docs-title: Code Example - How to Use AG-UI with Agent Spec
11+
12+
exit() # agui integration not installed
13+
# .. start-##_Creating_the_agent
14+
import os
15+
from typing import Dict, Any
16+
17+
import dotenv
18+
dotenv.load_dotenv()
19+
20+
from pyagentspec.agent import Agent
21+
from pyagentspec.llms import OpenAiCompatibleConfig
22+
from pyagentspec.tools import ServerTool
23+
from pyagentspec.property import StringProperty
24+
from pyagentspec.serialization import AgentSpecSerializer
25+
26+
def get_weather(location: str) -> Dict[str, Any]:
27+
"""
28+
Get the weather for a given location.
29+
"""
30+
import time
31+
time.sleep(1) # simulate tool execution
32+
return {
33+
"temperature": 20,
34+
"conditions": "sunny",
35+
"humidity": 50,
36+
"wind_speed": 10,
37+
"feelsLike": 25,
38+
}
39+
40+
tool_input_property = StringProperty(
41+
title="location",
42+
description="The location to get the weather forecast. Must be a city/town name."
43+
)
44+
weather_result_property = StringProperty(title="weather_result")
45+
46+
weather_tool = ServerTool(
47+
name="get_weather",
48+
description="Get the weather for a given location.",
49+
inputs=[tool_input_property],
50+
outputs=[weather_result_property],
51+
)
52+
53+
agent_llm = OpenAiCompatibleConfig(
54+
name="my_llm",
55+
model_id=os.environ.get("OPENAI_MODEL", "gpt-4o"),
56+
url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1")
57+
)
58+
59+
agent = Agent(
60+
name="my_agent",
61+
llm_config=agent_llm,
62+
system_prompt="Based on the weather forecaset result and the user input, write a response to the user",
63+
tools=[weather_tool],
64+
human_in_the_loop=True,
65+
)
66+
67+
backend_tool_rendering_agent_json = AgentSpecSerializer().to_json(agent)
68+
tool_registry = {"get_weather": get_weather}
69+
# .. end-##_Creating_the_agent
70+
# .. start-##_Creating_the_app
71+
import os
72+
import importlib.util
73+
import logging
74+
from fastapi import APIRouter, FastAPI
75+
76+
from ag_ui_agentspec.agent import AgentSpecAgent
77+
from ag_ui_agentspec.endpoint import add_agentspec_fastapi_endpoint
78+
79+
logger = logging.getLogger(__name__)
80+
router = APIRouter()
81+
82+
83+
def _is_available(module_name: str) -> bool:
84+
return importlib.util.find_spec(module_name) is not None
85+
86+
87+
def _mount(router: APIRouter):
88+
# LangGraph
89+
if _is_available("langgraph"):
90+
add_agentspec_fastapi_endpoint(
91+
app=router,
92+
agentspec_agent=AgentSpecAgent(
93+
backend_tool_rendering_agent_json,
94+
runtime="langgraph",
95+
tool_registry=tool_registry,
96+
),
97+
path="/langgraph/backend_tool_rendering",
98+
)
99+
else:
100+
logger.info("LangGraph not available. Skipping LangGraph endpoints.")
101+
102+
# Wayflow
103+
# The comment mentioned 'wayflowcore' specifically
104+
if _is_available("wayflowcore"):
105+
add_agentspec_fastapi_endpoint(
106+
app=router,
107+
agentspec_agent=AgentSpecAgent(
108+
backend_tool_rendering_agent_json,
109+
runtime="wayflow",
110+
tool_registry=tool_registry,
111+
),
112+
path="/wayflow/backend_tool_rendering",
113+
)
114+
else:
115+
logger.info("Wayflow (wayflowcore) not available. Skipping Wayflow endpoints.")
116+
117+
# Create the Web App
118+
119+
app = FastAPI(title="Agent-Spec × AG-UI Examples")
120+
_mount(router)
121+
app.include_router(router)
122+
port = int(os.getenv("PORT", "9003"))
123+
# if __name__=="__main__":
124+
# import uvicorn
125+
# uvicorn.run("server:app", host="0.0.0.0", port=port, reload=True)
126+
# .. end-##_Creating_the_app

‎docs/pyagentspec/source/howtoguides/howto_ag_ui.rst‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
================================
2+
How to Use AG-UI with Agent Spec
3+
================================
4+
5+
6+
`AG-UI <https://docs.ag-ui.com/>`_ is an open, event-based protocol and set of clients that connect agent backends to user interfaces for real-time, stateful, tool-aware experiences.
7+
8+
With the Agent Spec x AG-UI integration, you can take a portable Agent Spec configuration (JSON) and interact with it in AG-UI frontends, while keeping your choice of runtime (LangGraph, WayFlow).
9+
The adapter bridges Agent Spec Tracing and AG-UI events so frontends receive standardized messages, tool activity, and UI state without bespoke wiring.
10+
11+
In this guide, you will:
12+
13+
- Configure an Agent Spec agent with a tool suitable for UI rendering
14+
- Expose AG-UI endpoints with FastAPI using the Agent Spec adapter
15+
- Run locally and connect an AG-UI client to any available runtime
16+
17+
.. seealso::
18+
19+
See the starter template project building AI agents using Agent Spec and CopilotKit.
20+
21+
https://github.com/copilotkit/with-agent-spec
22+
23+
24+
.. image:: ../_static/howto/ag_ui_integration.jpg
25+
:align: center
26+
:scale: 20%
27+
:alt: Agent Spec enables developers to switch between runtime frameworks when using AG-UI
28+
29+
30+
31+
Prerequisites
32+
=============
33+
34+
- Python 3.10 to 3.13
35+
36+
Install the AG-UI Agent Spec integration from source:
37+
38+
.. code-block:: bash
39+
40+
git clone git@github.com:ag-ui-protocol/ag-ui.git
41+
cd ag-ui/integrations/agent-spec/python
42+
pip install -e .
43+
44+
This will install pyagentspec will the corresponding adapters for the different frameworks (LangGraph, WayFlow).
45+
46+
47+
Step 1. Configure your Agent
48+
============================
49+
50+
Create an agent with a tool that the UI can render and confirm.
51+
The example includes a weather tool and enables human-in-the-loop
52+
so the UI can request approvals before executing tools.
53+
54+
.. literalinclude:: ../code_examples/howto_ag_ui.py
55+
:language: python
56+
:start-after: .. start-##_Creating_the_agent
57+
:end-before: .. end-##_Creating_the_agent
58+
59+
This agent definition is exported to Agent Spec JSON and kept runtime-agnostic.
60+
The adapter will load it for any supported runtime.
61+
62+
63+
Here is what the **Agent Spec representation will look like ↓**
64+
65+
.. collapse:: Click here to see the assistant configuration.
66+
67+
.. tabs::
68+
69+
.. tab:: JSON
70+
71+
.. literalinclude:: ../agentspec_config_examples/howto_ag_ui.json
72+
:language: json
73+
74+
.. tab:: YAML
75+
76+
.. literalinclude:: ../agentspec_config_examples/howto_ag_ui.yaml
77+
:language: yaml
78+
79+
80+
81+
Step 2: Configure a FastAPI endpoint
82+
====================================
83+
84+
Expose AG-UI endpoints with the Agent Spec adapter. The example auto-detects installed runtimes and mounts one endpoint per runtime:
85+
86+
- ``/langgraph/backend_tool_rendering`` when ``langgraph`` is installed
87+
- ``/wayflow/backend_tool_rendering`` when ``wayflowcore`` is installed
88+
89+
.. literalinclude:: ../code_examples/howto_ag_ui.py
90+
:language: python
91+
:start-after: .. start-##_Creating_the_app
92+
:end-before: .. end-##_Creating_the_app
93+
94+
Run locally with Uvicorn (development only):
95+
96+
.. code-block:: bash
97+
98+
# If the app is in a module named "howto_ag_ui.py"
99+
uvicorn howto_ag_ui:app --reload --port 8000
100+
101+
102+
.. important::
103+
104+
This setup is intended for prototyping. Do not expose these endpoints publicly without proper authentication, rate limiting, and CORS controls.
105+
106+
107+
Once the development server is running, navigate to your local AG-UI hosted website and
108+
you should see your Agent Spec + AG-UI + CopilotKit agents up and running.
109+
110+
111+
.. image:: ../_static/howto/ag_ui_screenshot.png
112+
:align: center
113+
:scale: 30%
114+
:alt: Agent Spec with AG-UI Screenshot
115+
116+
117+
.. note::
118+
The adapter maps Agent Spec Tracing spans/events to AG-UI events so frontends receive standardized messages and tool activity without extra glue code.
119+
120+
121+
Recap
122+
=====
123+
124+
In this guide you:
125+
126+
- Defined an Agent Spec agent with a UI-renderable tool and HITL enabled
127+
- Exposed AG-UI endpoints via FastAPI for all available runtimes
128+
- Ran the server locally and prepared to connect an AG-UI client
129+
130+
131+
Next steps
132+
==========
133+
134+
Having learned how to connect Agent Spec agents to AG-UI, you may now proceed to:
135+
136+
- :doc:`Specify the Generation Configuration when Using LLMs <howto_generation_config>`
137+
- :doc:`How to Develop an Agent with Remote Tools <howto_agent_with_remote_tools>`
138+
- :doc:`How to Execute Agent Spec Configuration with WayFlow <howto_execute_agentspec_with_wayflow>`
139+
- :doc:`How to Execute Agent Spec Across Frameworks <howto_execute_agentspec_across_frameworks>`

‎docs/pyagentspec/source/howtoguides/index.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,20 @@ These guides demonstrate how to configure components in Agent Spec.
6161
Specify the Generation Configuration when Using LLMs <howto_generation_config>
6262
How to Use Disaggregated Config <howto_disaggregated_config>
6363

64+
65+
Ecosystem
66+
---------
67+
68+
With expanding integrations and community partnerships, Agent Spec streamlines building, running, and monitoring agents across heterogeneous environments.
69+
70+
For more information about the Agent Spec ecosystem, see :ref:`integrations <integrations>` and :ref:`collaborations <collaborations>`.
71+
72+
.. toctree::
73+
:maxdepth: 1
74+
75+
How to Use AG-UI with Agent Spec <howto_ag_ui>
76+
77+
6478
External Features
6579
-----------------
6680

0 commit comments

Comments
 (0)