agents-ui Python SDK

Python SDK for the agents-ui terminal workspace application. Provides complete programmatic access to all 68 API methods — sessions, projects, files, SSH, recordings, 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 — all 68 API methods across 14 namespaces
• Typed models — frozen dataclasses for every domain object with full IDE autocompletion
• Event streaming — subscribe to real-time terminal output, 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	16	Terminal session lifecycle and I/O
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.ui	5	UI control and state
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")

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

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

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/

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.