diff --git a/agent-os/interfaces/ag-ui/introduction.mdx b/agent-os/interfaces/ag-ui/introduction.mdx index db4c62a33..8f39c2b39 100644 --- a/agent-os/interfaces/ag-ui/introduction.mdx +++ b/agent-os/interfaces/ag-ui/introduction.mdx @@ -1,151 +1,237 @@ --- title: AG-UI -description: Expose Agno agents via the AG-UI protocol +sidebarTitle: Overview +description: Expose Agno agents and teams over the AG-UI protocol for streaming frontends. +keywords: [ag-ui, agui, interface, protocol, streaming, copilotkit, dojo, frontend, tools, events] --- -AG-UI, the [Agent-User Interaction Protocol](https://github.com/ag-ui-protocol/ag-ui), standardizes how AI agents connect to frontend applications. +The AG-UI interface exposes an Agno agent or team over the [Agent-User Interaction Protocol](https://docs.ag-ui.com/), a streaming event protocol that frontends like CopilotKit and Dojo consume. -**Migration from Apps**: For migration from `AGUIApp`, see the [v2 migration guide](/other/v2-migration#7-apps-interfaces) for complete steps. +Migrating from `AGUIApp`? See the [v2 migration guide](/other/v2-migration#7-apps-interfaces). -## Example usage +## Setup - - +Follow the [AG-UI setup guide](/agent-os/interfaces/ag-ui/setup) to run the backend and connect a frontend. -```bash -uv pip install ag-ui-protocol -``` + +Install the AG-UI dependencies: `uv pip install 'agno[agui]'` + + +Required configuration: + +- `OPENAI_API_KEY`, or a key for whichever model provider you use. +- A frontend pointed at the `{prefix}/agui` endpoint. Use [Dojo](https://github.com/ag-ui-protocol/ag-ui) for local development. - - - Expose an Agno agent through the AG-UI interface using `AgentOS` and `AGUI`. +AG-UI uses no tokens, OAuth, or signing secrets. The protocol endpoint is open by default. +## Example Usage + + + ```python basic.py -from agno.agent.agent import Agent +from agno.agent import Agent from agno.models.openai import OpenAIResponses from agno.os import AgentOS from agno.os.interfaces.agui import AGUI -chat_agent = Agent(model=OpenAIResponses(id="gpt-5.5")) +chat_agent = Agent( + name="Assistant", + model=OpenAIResponses(id="gpt-5.4"), + instructions="You are a helpful AI assistant.", + add_datetime_to_context=True, + markdown=True, +) + +agent_os = AgentOS( + agents=[chat_agent], + interfaces=[AGUI(agent=chat_agent)], +) +app = agent_os.get_app() -agent_os = AgentOS(agents=[chat_agent], interfaces=[AGUI(agent=chat_agent)]) +if __name__ == "__main__": + agent_os.serve(app="basic:app", reload=True, port=9001) +``` + + +```python research_team.py +from agno.agent import Agent +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.os.interfaces.agui import AGUI +from agno.team import Team +from agno.tools.websearch import WebSearchTools + +researcher = Agent( + name="researcher", + role="Research Assistant", + model=OpenAIResponses(id="gpt-5.4"), + tools=[WebSearchTools()], +) + +writer = Agent( + name="writer", + role="Content Writer", + model=OpenAIResponses(id="gpt-5.4"), +) + +research_team = Team( + name="research_team", + members=[researcher, writer], + instructions="Use the researcher to gather information, then the writer to create content.", +) + +agent_os = AgentOS( + teams=[research_team], + interfaces=[AGUI(team=research_team)], +) app = agent_os.get_app() if __name__ == "__main__": - agent_os.serve(app="basic:app", reload=True) + agent_os.serve(app="research_team:app", reload=True, port=9001) ``` + + - - + +See [more examples](/agent-os/usage/interfaces/ag-ui/basic) including [agents with tools](/agent-os/usage/interfaces/ag-ui/agent-with-tools), [reasoning](/agent-os/usage/interfaces/ag-ui/reasoning-agent), and [teams](/agent-os/usage/interfaces/ag-ui/team). + -Use Dojo (`ag-ui`'s frontend) as an advanced, customizable interface for AG-UI agents. +The examples serve on port `9001`, which Dojo expects. See the [setup guide](/agent-os/interfaces/ag-ui/setup) to run a frontend. -1. Clone: `git clone https://github.com/ag-ui-protocol/ag-ui.git` -2. Install dependencies in `/ag-ui/typescript-sdk`: `pnpm install` -3. Build the Agno package in `/ag-ui/integrations/agno`: `pnpm run build` -4. Start Dojo following the instructions in the repository. +## Sessions & State - - +AG-UI frontends send a `thread_id`, optional `state`, and the full message history with every request. The interface maps these to Agno and uses only the latest user message, letting the agent manage history through its session database. -With Dojo running, open `http://localhost:3000` and select the Agno agent. +| AG-UI field | Maps to | Purpose | +| --- | --- | --- | +| `thread_id` | `session_id` | Each thread is a separate conversation. | +| `state` | `session_state` | Shared state available to the agent during the run. | +| `forwarded_props.user_id` | `user_id` | Per-user memory and history. | - - +Configure a database on the agent or team to persist history across restarts. -Additional examples are available in the [cookbook](https://github.com/agno-agi/agno/tree/main/cookbook/05_agent_os/interfaces/agui/). +## Reasoning -## Custom Events +Reasoning streams to the frontend as AG-UI reasoning events. Native reasoning models and the `ReasoningTools` toolkit are both supported. + +See the [reasoning agent example](/agent-os/usage/interfaces/ag-ui/reasoning-agent). + +## Structured Output -Custom events created in tools are automatically delivered to AG-UI in the AG-UI custom event format. +Set `output_schema` to a Pydantic model to return typed output. The structured result streams to the frontend as content. -**Creating custom events:** +See the [structured output example](/agent-os/usage/interfaces/ag-ui/structured-output). + +## Frontend Tools + +Tools marked `external_execution=True` run on the frontend instead of the backend. The interface streams the tool call to the client, the client executes it, and the result returns on the next request. + +```python +from agno.tools import tool + +@tool(external_execution=True) +def generate_haiku(topic: str) -> str: + """Generate a haiku and display it in the frontend.""" + return "Haiku generated and displayed in frontend" +``` + +Add `external_execution_silent=True` to suppress the assistant's "I have tools to execute" message for cleaner UX. + +See the [agent with tools example](/agent-os/usage/interfaces/ag-ui/agent-with-tools). + +## Custom Events + +Tools can yield custom events, which the interface delivers to the frontend in the AG-UI custom event format. ```python from dataclasses import dataclass from agno.run.agent import CustomEvent +from agno.tools import tool @dataclass class CustomerProfileEvent(CustomEvent): customer_name: str customer_email: str -``` - -**Yielding from tools:** - -```python -from agno.tools import tool @tool() async def get_customer_profile(customer_id: str): customer = fetch_customer(customer_id) - yield CustomerProfileEvent( customer_name=customer["name"], customer_email=customer["email"], ) - return f"Profile retrieved for {customer['name']}" ``` -Custom events are streamed in real-time to the AG-UI frontend. +See [Custom Events](/agents/running-agents#custom-events) for details. -See [Custom Events documentation](/agents/running-agents#custom-events) for more details. +## Multiple Instances -## Core Components +Run multiple agents or teams on one server by giving each `AGUI` interface a different `prefix`: -- `AGUI` (interface): Wraps an Agno `Agent` or `Team` into an AG-UI compatible FastAPI router. -- `AgentOS.serve`: Serves the FastAPI app (including the AGUI router) with Uvicorn. - -`AGUI` mounts protocol-compliant routes on the app. - -## `AGUI` interface +```python +agent_os = AgentOS( + agents=[chat_agent, research_agent], + interfaces=[ + AGUI(agent=chat_agent, prefix="/chat"), + AGUI(agent=research_agent, prefix="/web-research"), + ], +) +``` -Main entry point for AG-UI exposure. +Each instance mounts its own `{prefix}/agui` and `{prefix}/status` endpoints. -### Initialization Parameters +## Security -| Parameter | Type | Default | Description | -| --------- | ------------------------------------- | ----------- | ---------------------------------------------- | -| `agent` | `Optional[Union[Agent, RemoteAgent]]` | `None` | Agno `Agent` or `RemoteAgent` instance. | -| `team` | `Optional[Union[Team, RemoteTeam]]` | `None` | Agno `Team` or `RemoteTeam` instance. | -| `prefix` | `str` | `""` | Route prefix (e.g., `/chat`, `/web-research`). | -| `tags` | `Optional[List[str]]` | `["AGUI"]` | OpenAPI tags for the router. | +The AG-UI endpoint is open by default and sets permissive CORS headers (`Access-Control-Allow-Origin: *`). It performs no signature verification or authentication. -Provide `agent` or `team`. + +Add authentication and restrict CORS before exposing the endpoint in production. The defaults suit local development with Dojo. + -### Key Method +## Troubleshooting -| Method | Parameters | Return Type | Description | -| ------------ | ---------- | ----------- | -------------------------------------------------------- | -| `get_router` | None | `APIRouter` | Returns the AG-UI FastAPI router and attaches endpoints. | + + + **Cause:** The AG-UI protocol package is missing. -## Endpoints + **Fix:** Install it with `uv pip install 'agno[agui]'`. + -Mounted at the interface's route prefix (root by default): + + **Cause:** Port mismatch. Dojo runs on `http://localhost:3000` and expects the backend on port `9001`. -- `POST /agui`: Main entrypoint. Accepts `RunAgentInput` from `ag-ui-protocol`. Streams AG-UI events. -- `GET /status`: Health/status endpoint for the interface. + **Fix:** Serve the backend with `agent_os.serve(app=..., port=9001)` and confirm the frontend points at `http://localhost:9001`. + -Refer to `ag-ui-protocol` docs for payload details. + + **Cause:** The frontend is not reading the event stream, or a proxy is buffering it. -## Serving AgentOS + **Fix:** Confirm the request hits `POST {prefix}/agui` and that any proxy passes `text/event-stream` through without buffering. + -Use `AgentOS.serve` to run the app with Uvicorn. + + **Cause:** A proxy or gateway is stripping the interface's CORS headers. -### Parameters + **Fix:** The interface sets `Access-Control-Allow-Origin: *` by default. Confirm your deployment layer preserves these headers. + + -| Parameter | Type | Default | Description | -| ----------------- | --------------------- | ------------- | ---------------------------------------------------- | -| `app` | `Union[str, FastAPI]` | required | FastAPI app instance or import string. | -| `host` | `str` | `"localhost"` | Host to bind. Override with `AGENT_OS_HOST` env var. | -| `port` | `int` | `7777` | Port to bind. Override with `AGENT_OS_PORT` env var. | -| `reload` | `bool` | `False` | Enable auto-reload for development. | -| `reload_includes` | `Optional[List[str]]` | `None` | File patterns to watch. Auto-adds `*.yaml`, `*.yml`. | -| `reload_excludes` | `Optional[List[str]]` | `None` | File patterns to exclude from reload. | -| `workers` | `Optional[int]` | `None` | Number of Uvicorn worker processes. | -| `access_log` | `bool` | `False` | Enable Uvicorn access logging. | +## Developer Resources -See [cookbook examples](https://github.com/agno-agi/agno/tree/main/cookbook/05_agent_os/interfaces/agui/) for updated interface patterns. + + + Run the backend and connect a Dojo frontend step by step. + + + Parameters, endpoints, and the Agno to AG-UI event map. + + + Serve the protocol endpoint for frontend integration. + + + Tools, reasoning, structured output, teams, and multiple instances. + + diff --git a/agent-os/interfaces/ag-ui/reference.mdx b/agent-os/interfaces/ag-ui/reference.mdx new file mode 100644 index 000000000..7780e6592 --- /dev/null +++ b/agent-os/interfaces/ag-ui/reference.mdx @@ -0,0 +1,83 @@ +--- +title: AG-UI Reference +sidebarTitle: Reference +description: Interface parameters, endpoints, and the Agno to AG-UI event map. +keywords: [ag-ui, agui, reference, parameters, endpoints, events, protocol, api] +--- + +## Interface Parameters + +Pass one of `agent` or `team` to the `AGUI` constructor. + +```python +from agno.os.interfaces.agui import AGUI + +AGUI(agent=my_agent, prefix="/chat") +``` + +| Parameter | Type | Default | Description | +| --- | --- | --- | --- | +| `agent` | `Optional[Union[Agent, RemoteAgent]]` | `None` | Agno `Agent` to expose over AG-UI. | +| `team` | `Optional[Union[Team, RemoteTeam]]` | `None` | Agno `Team` to expose over AG-UI. | +| `prefix` | `str` | `""` | URL prefix for the AG-UI endpoints (e.g., `/chat` serves `/chat/agui`). | +| `tags` | `Optional[List[str]]` | `["AGUI"]` | FastAPI route tags for API documentation. | + +Provide `agent` or `team`. The constructor raises `ValueError` if neither is set. + +## Endpoints + +Available at the interface prefix (root by default, customizable with `prefix`). + +### `POST {prefix}/agui` + +Accepts a `RunAgentInput` payload and returns a Server-Sent Events stream (`text/event-stream`) of AG-UI protocol events. + +| Status | Description | +| --- | --- | +| **200** | Event stream opened. Agent errors surface as a `RUN_ERROR` event inside the stream, not as an HTTP error. | +| **422** | Request body failed `RunAgentInput` validation. | + +The endpoint sets permissive CORS headers (`Access-Control-Allow-Origin: *`) for local frontend development. + +### `GET {prefix}/status` + +Health check. Returns `{"status": "available"}`. + +## Event Mapping + +The interface translates the Agno run stream into AG-UI protocol events. + +| Agno event | AG-UI event(s) | +| --- | --- | +| Run start | `RUN_STARTED` | +| Text content | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | +| Tool call started | `TOOL_CALL_START`, `TOOL_CALL_ARGS` | +| Tool call completed | `TOOL_CALL_END`, `TOOL_CALL_RESULT` | +| Reasoning started | `REASONING_START`, `REASONING_MESSAGE_START` | +| Reasoning content | `REASONING_MESSAGE_CONTENT` | +| Reasoning completed | `REASONING_MESSAGE_END`, `REASONING_END` | +| Custom event | `CUSTOM` | +| Paused for external execution | `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END` (executed on the frontend) | +| Run completed | `RUN_FINISHED` | +| Run error | `RUN_ERROR` | + + +Reasoning works with both native reasoning models and the `ReasoningTools` toolkit. Frontend tools (`external_execution=True`) stream as tool calls the client executes and returns on the next request. + + +## Developer Resources + + + + Sessions, reasoning, structured output, and troubleshooting. + + + Run the backend and connect a Dojo frontend. + + + Serve the protocol endpoint for frontend integration. + + + Official protocol specification and SDKs. + + diff --git a/agent-os/interfaces/ag-ui/setup.mdx b/agent-os/interfaces/ag-ui/setup.mdx new file mode 100644 index 000000000..0d1f0a217 --- /dev/null +++ b/agent-os/interfaces/ag-ui/setup.mdx @@ -0,0 +1,82 @@ +--- +title: Setup +sidebarTitle: Setup +description: Install AG-UI, run an Agno backend, and connect a Dojo frontend. +keywords: [ag-ui, agui, setup, dojo, frontend, copilotkit, installation] +--- + + +Install the AG-UI dependencies: `uv pip install 'agno[agui]'` + + + + + +Expose an Agno agent or team through `AgentOS` and `AGUI`. + +```python basic.py +from agno.agent import Agent +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.os.interfaces.agui import AGUI + +chat_agent = Agent(model=OpenAIResponses(id="gpt-5.4")) + +agent_os = AgentOS(agents=[chat_agent], interfaces=[AGUI(agent=chat_agent)]) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="basic:app", reload=True, port=9001) +``` + + +Serve on port `9001`. Dojo expects the backend there by default. + + + + +```bash +export OPENAI_API_KEY="your-api-key" +``` + +AG-UI needs no tokens, OAuth, or signing secrets. Set only your model provider's key. + + + +```bash +python basic.py +``` + +The AgentOS configuration is available at `http://localhost:9001/config`. + + + +Dojo is the AG-UI reference frontend. + +1. Clone the repository: + ```bash + git clone https://github.com/ag-ui-protocol/ag-ui.git + ``` +2. Install the TypeScript SDK: + ```bash + cd ag-ui/typescript-sdk && pnpm install + ``` +3. Build the Agno integration: + ```bash + cd integrations/agno && pnpm run build + ``` +4. Start Dojo: + ```bash + cd ../../apps/dojo && pnpm run dev + ``` + + + +Open [http://localhost:3000](http://localhost:3000) and select the Agno integration. Responses stream from your backend over the AG-UI protocol. + + + + + +Using your own frontend instead of Dojo? Point any AG-UI-compatible client (including CopilotKit) at the `{prefix}/agui` endpoint, for example `http://localhost:9001/agui`. + diff --git a/agent-os/usage/interfaces/ag-ui/agent-with-silent-tools.mdx b/agent-os/usage/interfaces/ag-ui/agent-with-silent-tools.mdx new file mode 100644 index 000000000..9b82e95fe --- /dev/null +++ b/agent-os/usage/interfaces/ag-ui/agent-with-silent-tools.mdx @@ -0,0 +1,103 @@ +--- +title: Agent with Silent Tools +description: Suppress frontend tool-execution messages over the AG-UI protocol. +--- + +## Code + +```python cookbook/05_agent_os/interfaces/agui/agent_with_silent_tools.py +from agno.agent.agent import Agent +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.os.interfaces.agui import AGUI +from agno.tools import tool +from agno.tools.duckduckgo import DuckDuckGoTools + + +@tool(external_execution=True, external_execution_silent=True) +def generate_haiku(topic: str) -> str: + """Generate a haiku about a given topic and display it in the frontend. + + Args: + topic: The topic for the haiku (e.g., "nature", "technology", "love") + + Returns: + Confirmation that the haiku was generated and displayed + """ + return f"Haiku about '{topic}' generated and displayed in frontend" + + +agent = Agent( + model=OpenAIResponses(id="gpt-5.4"), + tools=[ + DuckDuckGoTools(), + generate_haiku, + ], + description="You are a helpful AI assistant with backend and frontend tools. You can search the web and create haikus that render in the frontend.", + instructions=""" + You are a versatile AI assistant with the following capabilities: + + **Tools (executed on server):** + - Web search using DuckDuckGo for finding current information + + **Frontend Tools (executed on client):** + - generate_haiku: Creates a haiku about a given topic + + Always be helpful, creative, and use the most appropriate tool for each request! + """, + add_datetime_to_context=True, + add_history_to_context=True, + add_location_to_context=True, + timezone_identifier="Etc/UTC", + markdown=True, + debug_mode=True, +) + +agent_os = AgentOS( + agents=[agent], + interfaces=[AGUI(agent=agent)], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="agent_with_silent_tools:app", port=9001, reload=True) +``` + +## Usage + + + + + + ```bash + export OPENAI_API_KEY=your_openai_api_key + ``` + + + + ```bash + uv pip install 'agno[agui]' ddgs + ``` + + + + ```bash + python cookbook/05_agent_os/interfaces/agui/agent_with_silent_tools.py + ``` + + + +## Key Features + +- **Silent Frontend Tools**: `external_execution_silent=True` hides the "I have tools to execute" message +- **Backend Tools**: `DuckDuckGoTools` runs on the server +- **Frontend Tools**: `generate_haiku` runs in the browser via `external_execution=True` +- **Cleaner UX**: Frontend tool calls happen without verbose status chatter + +## Setup Frontend + +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` +4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` +5. Open `http://localhost:3000` and select the Agno integration diff --git a/agent-os/usage/interfaces/ag-ui/agent-with-tools.mdx b/agent-os/usage/interfaces/ag-ui/agent-with-tools.mdx index 4a009263e..5a5f36924 100644 --- a/agent-os/usage/interfaces/ag-ui/agent-with-tools.mdx +++ b/agent-os/usage/interfaces/ag-ui/agent-with-tools.mdx @@ -1,28 +1,50 @@ --- -title: "Agent with Tools" -description: "Investment analyst agent with financial tools and web interface" +title: Agent with Tools +description: Combine backend and frontend tools over the AG-UI protocol. --- ## Code ```python cookbook/05_agent_os/interfaces/agui/agent_with_tools.py +from typing import List + from agno.agent.agent import Agent from agno.models.openai import OpenAIResponses from agno.os import AgentOS from agno.os.interfaces.agui import AGUI -from agno.tools.yfinance import YFinanceTools +from agno.tools import tool +from agno.tools.websearch import WebSearchTools + + +@tool(external_execution=True) +def generate_haiku( + english: List[str], japanese: List[str], image_names: List[str] +) -> str: + """Generate a haiku in Japanese and English and display it in the frontend.""" + return "Haiku generated and displayed in frontend" + agent = Agent( - model=OpenAIResponses(id="gpt-5.5"), + model=OpenAIResponses(id="gpt-5.4"), tools=[ - YFinanceTools( - stock_price=True, - analyst_recommendations=True, - stock_fundamentals=True - ) + WebSearchTools(), + generate_haiku, ], - description="You are an investment analyst that researches stock prices, analyst recommendations, and stock fundamentals.", - instructions="Format your response using markdown and use tables to display data where possible.", + description="You are a helpful AI assistant with backend and frontend tools. You can search the web and create haikus that render in the frontend.", + instructions=""" + You are a versatile AI assistant with the following capabilities: + + **Tools (executed on server):** + - Web search using DuckDuckGo for finding current information + + Always be helpful, creative, and use the most appropriate tool for each request! + """, + add_datetime_to_context=True, + add_history_to_context=True, + add_location_to_context=True, + timezone_identifier="Etc/UTC", + markdown=True, + debug_mode=True, ) agent_os = AgentOS( @@ -32,7 +54,7 @@ agent_os = AgentOS( app = agent_os.get_app() if __name__ == "__main__": - agent_os.serve(app="agent_with_tools:app", reload=True) + agent_os.serve(app="agent_with_tools:app", port=9001, reload=True) ``` ## Usage @@ -46,9 +68,9 @@ if __name__ == "__main__": ``` - + ```bash - uv pip install -U agno yfinance + uv pip install 'agno[agui]' ddgs ``` @@ -61,9 +83,15 @@ if __name__ == "__main__": ## Key Features -- **Financial Data Tools**: Real-time stock prices, analyst recommendations, fundamentals -- **Investment Analysis**: Comprehensive company analysis and recommendations -- **Data Visualization**: Tables and formatted financial information -- **Web Interface**: Professional browser-based interaction -- **GPT-4o Powered**: Advanced reasoning for financial insights +- **Backend Tools**: `WebSearchTools` runs on the server +- **Frontend Tools**: `generate_haiku` runs in the browser via `external_execution=True` +- **Mixed Execution**: One agent orchestrates both server-side and client-side tools +- **Real-Time Streaming**: Tool calls and results stream to the frontend + +## Setup Frontend +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` +4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` +5. Open `http://localhost:3000` and select the Agno integration diff --git a/agent-os/usage/interfaces/ag-ui/basic.mdx b/agent-os/usage/interfaces/ag-ui/basic.mdx index 42432e685..6b36db32a 100644 --- a/agent-os/usage/interfaces/ag-ui/basic.mdx +++ b/agent-os/usage/interfaces/ag-ui/basic.mdx @@ -1,6 +1,6 @@ --- -title: "Basic" -description: "Create a basic AI agent with ChatGPT-like web interface" +title: Basic AG-UI Agent +description: Connect an Agno agent to a web frontend over the AG-UI protocol. --- ## Code @@ -13,7 +13,7 @@ from agno.os.interfaces.agui import AGUI chat_agent = Agent( name="Assistant", - model=OpenAIResponses(id="gpt-5.5"), + model=OpenAIResponses(id="gpt-5.4"), instructions="You are a helpful AI assistant.", add_datetime_to_context=True, markdown=True, @@ -26,7 +26,7 @@ agent_os = AgentOS( app = agent_os.get_app() if __name__ == "__main__": - agent_os.serve(app="basic:app", reload=True) + agent_os.serve(app="basic:app", reload=True, port=9001) ``` ## Usage @@ -40,9 +40,9 @@ if __name__ == "__main__": ``` - + ```bash - uv pip install -U agno ag-ui-protocol + uv pip install 'agno[agui]' ``` @@ -55,17 +55,16 @@ if __name__ == "__main__": ## Key Features -- **Web Interface**: ChatGPT-like conversation experience -- **Real-time Chat**: Instant message exchange -- **Markdown Support**: Rich text formatting in responses -- **DateTime Context**: Time-aware responses -- **Open Protocol**: Compatible with AG-UI frontends +- **Web Interface**: Browser-based chat through an AG-UI frontend like Dojo or CopilotKit +- **Real-Time Streaming**: Responses stream token-by-token +- **Markdown Support**: Rich text formatting in responses +- **DateTime Context**: Time-aware responses via `add_datetime_to_context` +- **Open Protocol**: Works with any AG-UI-compatible frontend ## Setup Frontend -1. Clone AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` -2. Install dependencies: `cd ag-ui/typescript-sdk && pnpm install` -3. Build integration: `cd integrations/agno && pnpm run build` +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` 4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` -5. Access at http://localhost:3000 - +5. Open `http://localhost:3000` and select the Agno integration diff --git a/agent-os/usage/interfaces/ag-ui/multiple-instances.mdx b/agent-os/usage/interfaces/ag-ui/multiple-instances.mdx new file mode 100644 index 000000000..5d4701ea7 --- /dev/null +++ b/agent-os/usage/interfaces/ag-ui/multiple-instances.mdx @@ -0,0 +1,86 @@ +--- +title: Multiple Instances +description: Serve multiple Agno agents over AG-UI from one AgentOS with different prefixes. +--- + +## Code + +```python cookbook/05_agent_os/interfaces/agui/multiple_instances.py +from agno.agent.agent import Agent +from agno.db.sqlite import SqliteDb +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.os.interfaces.agui import AGUI +from agno.tools.websearch import WebSearchTools + +db = SqliteDb(db_file="tmp/agentos.db") + +chat_agent = Agent( + name="Assistant", + model=OpenAIResponses(id="gpt-5.4"), + db=db, + instructions="You are a helpful AI assistant.", + add_datetime_to_context=True, + markdown=True, +) + +web_research_agent = Agent( + name="Web Research Agent", + model=OpenAIResponses(id="gpt-5.4"), + db=db, + tools=[WebSearchTools()], + instructions="You are a helpful AI assistant that can search the web.", + markdown=True, +) + +agent_os = AgentOS( + agents=[chat_agent, web_research_agent], + interfaces=[ + AGUI(agent=chat_agent, prefix="/chat"), + AGUI(agent=web_research_agent, prefix="/web-research"), + ], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="multiple_instances:app", reload=True, port=9001) +``` + +## Usage + + + + + + ```bash + export OPENAI_API_KEY=your_openai_api_key + ``` + + + + ```bash + uv pip install 'agno[agui]' ddgs + ``` + + + + ```bash + python cookbook/05_agent_os/interfaces/agui/multiple_instances.py + ``` + + + +## Key Features + +- **Multiple Endpoints**: Each `AGUI(prefix=...)` mounts its own `{prefix}/agui` endpoint +- **Shared AgentOS**: Two agents served from a single app +- **Per-Agent Tools**: The web research agent has `WebSearchTools`; the chat agent does not +- **Shared Database**: Both agents use the same `SqliteDb` + +## Setup Frontend + +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` +4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` +5. Open `http://localhost:3000` and select the Agno integration diff --git a/agent-os/usage/interfaces/ag-ui/reasoning-agent.mdx b/agent-os/usage/interfaces/ag-ui/reasoning-agent.mdx new file mode 100644 index 000000000..ae05b5805 --- /dev/null +++ b/agent-os/usage/interfaces/ag-ui/reasoning-agent.mdx @@ -0,0 +1,74 @@ +--- +title: Reasoning Agent +description: Stream an Agno reasoning agent's thinking to the frontend over AG-UI. +--- + +## Code + +```python cookbook/05_agent_os/interfaces/agui/reasoning_agent.py +from agno.agent.agent import Agent +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.os.interfaces.agui import AGUI +from agno.tools.websearch import WebSearchTools + +chat_agent = Agent( + name="Assistant", + model=OpenAIResponses(id="o4-mini"), + instructions="You are a helpful AI assistant.", + add_datetime_to_context=True, + add_history_to_context=True, + add_location_to_context=True, + timezone_identifier="Etc/UTC", + markdown=True, + tools=[WebSearchTools()], +) + +agent_os = AgentOS( + agents=[chat_agent], + interfaces=[AGUI(agent=chat_agent)], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="reasoning_agent:app", reload=True, port=9001) +``` + +## Usage + + + + + + ```bash + export OPENAI_API_KEY=your_openai_api_key + ``` + + + + ```bash + uv pip install 'agno[agui]' ddgs + ``` + + + + ```bash + python cookbook/05_agent_os/interfaces/agui/reasoning_agent.py + ``` + + + +## Key Features + +- **Native Reasoning**: `o4-mini` streams its reasoning as AG-UI `REASONING_*` events +- **Visible Thinking**: The frontend renders the agent's reasoning steps in real time +- **Web Search**: `WebSearchTools` pulls in current information +- **Context Aware**: Date, time, and location are added to the agent's context + +## Setup Frontend + +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` +4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` +5. Open `http://localhost:3000` and select the Agno integration diff --git a/agent-os/usage/interfaces/ag-ui/structured-output.mdx b/agent-os/usage/interfaces/ag-ui/structured-output.mdx new file mode 100644 index 000000000..28d4f0065 --- /dev/null +++ b/agent-os/usage/interfaces/ag-ui/structured-output.mdx @@ -0,0 +1,81 @@ +--- +title: Structured Output +description: Return typed Pydantic output from an Agno agent over AG-UI. +--- + +## Code + +```python cookbook/05_agent_os/interfaces/agui/structured_output.py +from typing import List + +from agno.agent.agent import Agent +from agno.models.openai import OpenAIResponses +from agno.os import AgentOS +from agno.os.interfaces.agui import AGUI +from pydantic import BaseModel, Field + + +class MovieScript(BaseModel): + setting: str = Field(..., description="Setting for the movie.") + ending: str = Field(..., description="How the movie ends.") + genre: str = Field(..., description="Genre, e.g. action or thriller.") + name: str = Field(..., description="Name of the movie.") + characters: List[str] = Field(..., description="Main characters.") + storyline: str = Field(..., description="A 3-sentence storyline.") + + +chat_agent = Agent( + name="Output Schema Agent", + model=OpenAIResponses(id="gpt-5.4"), + description="You write movie scripts.", + markdown=True, + output_schema=MovieScript, +) + +agent_os = AgentOS( + agents=[chat_agent], + interfaces=[AGUI(agent=chat_agent)], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="structured_output:app", port=9001, reload=True) +``` + +## Usage + + + + + + ```bash + export OPENAI_API_KEY=your_openai_api_key + ``` + + + + ```bash + uv pip install 'agno[agui]' + ``` + + + + ```bash + python cookbook/05_agent_os/interfaces/agui/structured_output.py + ``` + + + +## Key Features + +- **Structured Output**: `output_schema=MovieScript` returns a typed Pydantic object instead of free text +- **Pydantic Schema**: Fields with descriptions guide what the agent fills in +- **Streamed to Frontend**: The structured result streams as content over AG-UI + +## Setup Frontend + +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` +4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` +5. Open `http://localhost:3000` and select the Agno integration diff --git a/agent-os/usage/interfaces/ag-ui/team.mdx b/agent-os/usage/interfaces/ag-ui/team.mdx index 7f685957b..cc90b7028 100644 --- a/agent-os/usage/interfaces/ag-ui/team.mdx +++ b/agent-os/usage/interfaces/ag-ui/team.mdx @@ -1,6 +1,6 @@ --- -title: "Research Team" -description: "Multi-agent research team with specialized roles and web interface" +title: Research Team +description: Serve a multi-agent Agno team over the AG-UI protocol. --- ## Code @@ -11,20 +11,23 @@ from agno.models.openai import OpenAIResponses from agno.os import AgentOS from agno.os.interfaces.agui import AGUI from agno.team import Team +from agno.tools.websearch import WebSearchTools researcher = Agent( name="researcher", role="Research Assistant", - model=OpenAIResponses(id="gpt-5.5"), + model=OpenAIResponses(id="gpt-5.4"), instructions="You are a research assistant. Find information and provide detailed analysis.", + tools=[WebSearchTools()], markdown=True, ) writer = Agent( name="writer", - role="Content Writer", - model=OpenAIResponses(id="gpt-5.5"), + role="Content Writer", + model=OpenAIResponses(id="gpt-5.4"), instructions="You are a content writer. Create well-structured content based on research.", + tools=[WebSearchTools()], markdown=True, ) @@ -38,24 +41,17 @@ research_team = Team( show_members_responses=True, get_member_information_tool=True, add_member_tools_to_context=True, + add_history_to_context=True, ) -# Setup our AgentOS app agent_os = AgentOS( teams=[research_team], interfaces=[AGUI(team=research_team)], ) app = agent_os.get_app() - if __name__ == "__main__": - """Run our AgentOS. - - You can see the configuration and available apps at: - http://localhost:7777/config - - """ - agent_os.serve(app="research_team:app", reload=True) + agent_os.serve(app="research_team:app", reload=True, port=9001) ``` ## Usage @@ -69,9 +65,9 @@ if __name__ == "__main__": ``` - + ```bash - uv pip install -U agno + uv pip install 'agno[agui]' ddgs ``` @@ -84,15 +80,15 @@ if __name__ == "__main__": ## Key Features -- **Multi-Agent Collaboration**: Researcher and writer working together -- **Specialized Roles**: Distinct expertise and responsibilities -- **Transparent Process**: See individual agent contributions -- **Coordinated Workflow**: Structured research-to-content pipeline -- **Web Interface**: Professional team interaction through AG-UI - -## Team Members +- **Multi-Agent Team**: Researcher and writer collaborate on one request +- **Specialized Roles**: Each member has a distinct role and instructions +- **Visible Members**: `show_members_responses=True` surfaces each member's output +- **Shared Tools**: Members use `WebSearchTools` for current information -- **Researcher**: Information gathering and analysis specialist -- **Writer**: Content creation and structuring expert -- **Workflow**: Sequential collaboration from research to final content +## Setup Frontend +1. Clone the AG-UI repository: `git clone https://github.com/ag-ui-protocol/ag-ui.git` +2. Install the TypeScript SDK: `cd ag-ui/typescript-sdk && pnpm install` +3. Build the Agno integration: `cd integrations/agno && pnpm run build` +4. Start Dojo: `cd ../../apps/dojo && pnpm run dev` +5. Open `http://localhost:3000` and select the Agno integration diff --git a/deploy/interfaces/ag-ui/overview.mdx b/deploy/interfaces/ag-ui/overview.mdx index baa470563..4af5e06be 100644 --- a/deploy/interfaces/ag-ui/overview.mdx +++ b/deploy/interfaces/ag-ui/overview.mdx @@ -22,18 +22,21 @@ agent_os = AgentOS( interfaces=[AGUI(agent=agent)], ) app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="agui_agent:app", reload=True, port=9001) ``` ```bash uv pip install 'agno[agui]' -python -m agno.os.serve agui_agent:app --port 9001 +python agui_agent.py ``` ## How It Works | Concept | Behavior | | --- | --- | -| **Protocol** | AG-UI standard for agent ↔ frontend communication | +| **Protocol** | AG-UI standard for agent-to-frontend communication | | **Streaming** | Real-time token streaming with tool call visibility | | **Custom Events** | Stream structured data (charts, profiles) to frontend | | **Frontends** | Works with Dojo, CopilotKit, or any AG-UI client | @@ -48,15 +51,15 @@ No external configuration required. Run the agent and connect your frontend to t - Custom events, state sync, and frontend integration. + Sessions, reasoning, structured output, and troubleshooting. - - Basic agent, tools, and team examples. + + Run the backend and connect a Dojo frontend step by step. - - Full runnable examples on GitHub. + + Parameters, endpoints, and the Agno to AG-UI event map. - - Official protocol specification. + + Tools, reasoning, structured output, teams, and more. diff --git a/docs.json b/docs.json index 535216e92..22012dcec 100644 --- a/docs.json +++ b/docs.json @@ -4698,7 +4698,14 @@ ] }, "agent-os/interfaces/a2a/introduction", - "agent-os/interfaces/ag-ui/introduction" + { + "group": "AG-UI", + "pages": [ + "agent-os/interfaces/ag-ui/introduction", + "agent-os/interfaces/ag-ui/setup", + "agent-os/interfaces/ag-ui/reference" + ] + } ] }, { @@ -4811,6 +4818,10 @@ "pages": [ "agent-os/usage/interfaces/ag-ui/basic", "agent-os/usage/interfaces/ag-ui/agent-with-tools", + "agent-os/usage/interfaces/ag-ui/agent-with-silent-tools", + "agent-os/usage/interfaces/ag-ui/reasoning-agent", + "agent-os/usage/interfaces/ag-ui/structured-output", + "agent-os/usage/interfaces/ag-ui/multiple-instances", "agent-os/usage/interfaces/ag-ui/team" ] },