agents-ui Python SDK

Python SDK for the agents-ui terminal workspace application. Provides complete programmatic access to the full agents-ui API — 100+ methods across 18 namespaces: terminal sessions, projects, files, SSH, the embedded browser and file viewer, screenshots, shell integration, recordings, real-time events, and more.

This is the official Python client for agents-ui, a terminal workspace for AI coding agents.

Installation

pip install agents-ui-sdk

From source:

git clone https://github.com/FusionbaseHQ/agents-ui-python-sdk.git
cd agents-ui-python-sdk
pip install -e ".[dev]"

Quick Start

Async

import asyncio
from agents_ui import AgentsUIClient

async def main():
    async with AgentsUIClient() as client:
        # List projects
        projects = await client.projects.list()
        print(f"Projects: {[p.title for p in projects]}")

        # Create a session and run a command
        session = await client.sessions.create(projects[0].id, name="sdk-demo")
        await client.sessions.write(session.id, "echo hello world\r")

        # Subscribe to output events
        async with client.subscribe(["sessions.output"], session_id=session.id) as stream:
            async for event in stream:
                print(event.data.get("output", ""))
                break

asyncio.run(main())

Sync

from agents_ui import SyncAgentsUIClient

with SyncAgentsUIClient() as client:
    info = client.app.info()
    print(f"Connected to {info.name} v{info.version}")

    projects = client.projects.list()
    for project in projects:
        print(f"  - {project.title} ({project.id})")

Architecture

The SDK communicates with the agents-ui desktop application over a Unix domain socket using JSON-RPC 2.0. Connection parameters are automatically discovered from ~/.agents-ui/api.json.

Your Python code
      |
      v
 AgentsUIClient  (this SDK)
      |
      v  JSON-RPC 2.0 over Unix socket
      |
 agents-ui desktop app  (Tauri/Rust)
      |
      v  PTY / SSH / filesystem
      |
 Terminal sessions, files, SSH hosts

Key Features

• Async-first with a full synchronous wrapper — use whichever fits your project
• Auto-discovery — connection parameters are read from ~/.agents-ui/api.json automatically
• Complete coverage — 100+ API methods across 18 namespaces
• Agent-grade terminal control — send_command, send_signal, and wait_for_* helpers built on OSC 133 shell integration
• Typed models — frozen dataclasses for every domain object with full IDE autocompletion
• Event streaming — subscribe to real-time terminal output, command completion, session exits, and more
• Zero dependencies — stdlib only (asyncio, json, socket)

Namespaces

The client organizes methods into namespaces matching the API categories:

Namespace	Methods	Description
client.sessions	21	Terminal session lifecycle, I/O, and high-level control helpers
client.persistent_sessions	3	Background persistent sessions
client.projects	8	Workspace project management
client.prompts	7	Reusable command prompts
client.environments	5	Environment configurations
client.assets	7	Project asset templates
client.recordings	6	Session recording playback
client.ssh	4	SSH connection management
client.files	7	Local file operations
client.ssh_files	8	Remote SSH file operations
client.split_views	4	Terminal split panes
client.shell	5	Terminal screen/scrollback and shell-integration state
client.file_viewer	7	File/editor and embedded browser tabs
client.browser	6	Embedded browser navigation
client.capture	1	Screenshot capture of viewer/browser surfaces
client.ui	7	UI control, state, and theme
client.app	4	App info and event subscriptions
client.api	2	API introspection

Connection Override

# Use explicit connection parameters instead of auto-discovery
client = AgentsUIClient(
    socket_path="/path/to/api.sock",
    token="your-auth-token",
)

Error Handling

All API errors map to typed exceptions:

from agents_ui import AgentsUIClient, NotFoundError, RateLimitError

async with AgentsUIClient() as client:
    try:
        session = await client.sessions.get("nonexistent")
    except NotFoundError:
        print("Session not found")
    except RateLimitError:
        print("Too many requests")

Driving a terminal like an agent

The sessions namespace includes high-level helpers built on OSC 133 shell integration, so you can run a command and reliably capture its result:

session = await client.sessions.create(project_id, name="agent")

# Run a command and wait for it to finish (captures exit code + output).
import asyncio
wait = asyncio.create_task(client.sessions.wait_for_command_complete(session.id))
await asyncio.sleep(0.2)              # let the subscription register first
await client.sessions.send_command(session.id, "pytest -q")
result = await wait
print(result.exit_code, result.output)

# Interrupt a runaway command, then wait for the prompt to come back.
await client.sessions.send_command(session.id, "sleep 60")
await client.sessions.send_signal(session.id, "SIGINT")   # Ctrl+C
await client.sessions.wait_for_idle(session.id)

Inspect live terminal state with the shell namespace:

screen = await client.shell.read_screen(session.id)   # visible viewport + cursor
print(screen.content)

status = await client.shell.status(session.id)         # idle / running, cwd, exit
history = await client.shell.command_history(session.id, limit=10)

Shell integration must be active in the session for wait_for_command_complete, wait_for_idle, command_history, and last_result. read_screen, read_scrollback, and send_command/send_signal work in any session.

Embedded browser, file viewer & screenshots

Open file/editor and browser tabs in the workspace, drive the embedded browser, and capture PNG screenshots — all separate from terminal sessions:

# Open and navigate an embedded browser tab.
await client.file_viewer.open_browser("https://example.com")
await client.browser.navigate("https://www.python.org")
snap = await client.browser.snapshot()

# Save a screenshot of the rendered page.
shot = await client.capture.screenshot(target="browser", max_width=1200)
shot.save("page.png")                  # or use shot.png_bytes

# Open a file in the viewer and read its current text.
await client.file_viewer.open_file("/proj/README.md", mode="markdown")
fv = await client.file_viewer.snapshot()
print(fv.content)

Themes

current = await client.ui.get_theme()
await client.ui.set_theme("midnight")
# dawn, sepia, ember, slate, midnight, cobalt, neon, forest

Event Subscriptions

async with client.subscribe(["sessions.output", "sessions.exit"]) as stream:
    async for event in stream:
        if event.event == "sessions.output":
            print(f"[{event.session_id}] {event.data['output']}")
        elif event.event == "sessions.exit":
            print(f"Session {event.session_id} exited")
            break

Useful event names include sessions.output, sessions.exit, shell.command_complete (fires with command, exitCode, output, durationMs), shell.prompt_ready, and the *.created/*.updated/*.deleted lifecycle events for projects, prompts, sessions, and more. Subscribe with ["*"] to receive everything, or pass session_id= to filter to one session.

Utilities

Raw PTY output includes ANSI escape sequences. Use strip_ansi() for clean text:

from agents_ui import strip_ansi

clean = strip_ansi(raw_terminal_output)

Examples

The examples/ directory contains runnable scripts covering every major feature:

Example	Description
01_quickstart.py	Connect, list projects and sessions (async)
02_quickstart_sync.py	Same as above using the synchronous client
03_run_command.py	Create a session, run a command, capture output
04_file_operations.py	List, read, write, rename, and delete files
05_event_stream.py	Subscribe to real-time session output events
06_project_management.py	Create, update, list, and delete projects
07_ssh_hosts.py	List SSH hosts and connection history
08_prompts_and_environments.py	Manage reusable prompts and environment configs
09_recordings.py	List and load session recordings
10_api_introspection.py	Discover all available API methods at runtime
11_ui_and_theme.py	Control UI state, themes, and panel visibility
12_error_handling.py	Typed exceptions and error handling patterns
13_shell_control.py	Run commands, wait for completion, read screen, send signals
14_workspace_browser.py	Open file/browser tabs, navigate, and capture screenshots

Run any example (requires a running agents-ui instance):

python examples/01_quickstart.py

Development

git clone https://github.com/FusionbaseHQ/agents-ui-python-sdk.git
cd agents-ui-python-sdk
pip install -e ".[dev]"

# Run tests (no running app needed — uses a mock server)
pytest

# Type checking
mypy src/agents_ui/

What's new in 0.2.0

Full coverage of the agents-ui API surface — the SDK can now drive every part of the app:

• client.shell — read the live terminal screen, scrollback, shell status, and OSC 133 command history
• client.file_viewer — open, focus, close, and snapshot file/editor and embedded browser tabs
• client.browser — navigate embedded browser tabs (navigate, back/forward/reload, snapshot)
• client.capture — capture PNG screenshots of the viewer/browser (Screenshot.save() / .png_bytes)
• client.ui.get_theme / set_theme — read and switch the UI theme
• client.sessions — agent-style control helpers: send_command, send_signal, wait_for_output, wait_for_command_complete, wait_for_idle
• New typed models for all of the above, plus full IDE autocompletion across every namespace

Requirements

• Python 3.10+
• A running agents-ui desktop application
• Zero runtime dependencies (stdlib only)

Related Projects

• agents-ui — The terminal workspace application (Tauri/Rust + React)
• agents-ui.com — Project homepage and downloads

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the LICENSE file for the full license text.