Automate Terminal Workflows with Python: The Agents UI SDK

Most developers automate servers but not their terminals. You have Ansible for infrastructure, CI pipelines for builds, and cron for scheduled tasks. But the terminal itself — the place where you spend most of your day — stays manual. You open sessions by hand, type commands, watch output scroll by, and repeat.

Agents UI changes that. Every action in the terminal — sessions, commands, files, projects — is exposed as a programmable API. And with the open-source Python SDK, you can script, orchestrate, and automate all of it from any Python environment.

Why Automate Your Terminal?

The obvious answer is speed. But the deeper reason is reproducibility. When your deployment process lives in your muscle memory — "open three tabs, SSH into staging, run the build, tail the logs, check the health endpoint" — it works until you're tired, distracted, or handing off to someone else.

A Python script that does the same thing is runnable, testable, and version-controlled. It doesn't forget steps.

Here are real workflows developers automate with the SDK:

• Deployment pipelines that open sessions, run builds, and verify health checks
• Multi-agent orchestration that spins up parallel Claude Code and Codex sessions
• Environment setup that creates project structures with the right sessions and files on day one
• Monitoring dashboards that read terminal output and react to patterns

Getting Started

Install the SDK and make sure Agents UI is running:

pip install agents-ui-sdk

The SDK connects to your running Agents UI instance automatically via a local socket. No API keys, no cloud services, no configuration needed.

from agents_ui import SyncAgentsUIClient

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

That's it. If Agents UI is open, you're connected.

Core Concepts

The SDK mirrors the structure of Agents UI itself. Everything is organized into namespaces:

• client.projects — create and manage project workspaces
• client.sessions — open terminal sessions, send commands, read output
• client.files — read, write, and list local files
• client.ssh_files — same operations on remote hosts
• client.prompts — manage and send AI prompts to sessions

Each namespace has methods like .create(), .list(), .get(), and domain-specific actions. The sync client wraps an async core, so you can use AgentsUIClient with asyncio if you prefer.

Example: Automated Deployment in Four Steps

Here's a real deployment script. It creates a project, opens a session, runs the build, and verifies the result:

from agents_ui import SyncAgentsUIClient

with SyncAgentsUIClient() as client:
    # 1. Set up the project workspace
    project = client.projects.create(
        "production-deploy",
        base_path="/Users/me/myapp"
    )

    # 2. Open a session and run the build
    session = client.sessions.create(project.id, name="build")
    client.sessions.write(session.id, "npm run build\r")

    # 3. Open a second session for the deploy
    deploy = client.sessions.create(project.id, name="deploy")
    client.sessions.write(deploy.id, "npm run deploy -- --prod\r")

    # 4. Check production files
    entries = client.files.list("/Users/me/myapp", "dist")
    print(f"Build produced {len(entries)} artifacts")

No clicking, no tab management, no forgetting the --prod flag at 11pm.

Example: Orchestrating Multiple AI Agents

This is where the SDK gets interesting. You can spin up multiple agent sessions in parallel and let them work on different parts of a problem:

from agents_ui import SyncAgentsUIClient

with SyncAgentsUIClient() as client:
    project = client.projects.create("refactor", base_path="/app")

    # Spin up parallel agent sessions
    agents = {}
    for task_name in ["api-tests", "type-cleanup", "docs-update"]:
        session = client.sessions.create(project.id, name=task_name)
        agents[task_name] = session

    # Send each agent a different prompt
    client.prompts.send(
        agents["api-tests"].id,
        content="Write integration tests for all /api/v2 endpoints"
    )
    client.prompts.send(
        agents["type-cleanup"].id,
        content="Find and fix all TypeScript any types in src/lib"
    )
    client.prompts.send(
        agents["docs-update"].id,
        content="Update the README to reflect the new API routes"
    )

Three agents working simultaneously, each in their own session with full terminal access. You can check on them, read their output, or send follow-up prompts — all from your script.

Example: SSH Workflows

The SDK handles remote files through the same interface as local ones. If you manage servers, this means your automation scripts work across local and remote environments:

from agents_ui import SyncAgentsUIClient

with SyncAgentsUIClient() as client:
    host = "prod-server"

    # Read a remote config file
    config = client.ssh_files.read(host, "/etc/nginx", "nginx.conf")
    print(f"Current config: {len(config)} bytes")

    # List remote log files
    logs = client.ssh_files.list(host, "/var/log", "app")
    for entry in logs:
        print(f"  {entry.name}")

    # Update a remote file
    client.ssh_files.write(
        host, "/etc/nginx", "nginx.conf",
        config.replace("worker_connections 512", "worker_connections 1024")
    )

No separate paramiko setup. No managing SSH keys in your script. The SDK uses the SSH connections Agents UI already has, including your existing ~/.ssh/config.

Event Subscriptions: Reacting to Terminal Output

The async client supports subscribing to events — session output, exit signals, file changes. This lets you build reactive workflows:

import asyncio
from agents_ui import AgentsUIClient, strip_ansi

async def watch_build():
    async with AgentsUIClient() as client:
        project = await client.projects.create("ci", base_path="/app")
        session = await client.sessions.create(project.id, name="build")

        async with client.subscribe(
            ["sessions.output"],
            session_id=session.id
        ) as stream:
            await client.sessions.write(session.id, "npm test\r")

            async for event in stream:
                output = event.data.get("output", "")
                clean = strip_ansi(output)

                if "FAIL" in clean:
                    print(f"Test failure detected")
                    # Could trigger a notification, open a debug session, etc.
                    break
                elif "Tests:" in clean and "passed" in clean:
                    print("All tests passed")
                    break

asyncio.run(watch_build())

The strip_ansi utility cleans terminal escape codes from output, so your pattern matching works on plain text.

Building on Top of the SDK

The SDK is intentionally low-level. It gives you primitives — sessions, files, commands, prompts — and lets you compose them however you want. Some patterns developers have built:

• Project scaffolding scripts that create a project, open sessions for frontend/backend/tests, and pre-load each with the right working directory
• Daily standup automations that open yesterday's sessions, summarize what changed, and set up today's tasks
• CI integrations that trigger Agents UI workflows from GitHub Actions or local git hooks
• Custom dashboards that poll session output and display build status

Getting Involved

The Python SDK is open source under the MIT license:

• Repository: github.com/FusionbaseHQ/agents-ui-python-sdk
• Install: pip install agents-ui-sdk
• Requirements: Python 3.10+, a running Agents UI instance

The SDK has zero external dependencies — it uses only the Python standard library. It auto-discovers the Agents UI connection from ~/.agents-ui/api.json, so there's nothing to configure.

If you're already using Agents UI, the SDK is the natural next step. Stop clicking through workflows you could script. Start with one automation — a deploy script, a project setup, an agent orchestration — and build from there.