devops-bot-sdk 1.4.22

DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app

DevOpsBot SDK

Python client for the DevOpsBot desktop app. Provides the agentos CLI to configure credentials and a BackendClient to interact with the DevOpsBot backend.

Private package — requires GitHub access to install.

For a full walkthrough including SSH setup, end-to-end testing, and troubleshooting see SETUP_GUIDE.md.

---

Requirements

	Minimum	Check
Python	3.11+	python3 --version (Linux/macOS) · python --version (Windows)
Git	any	git --version
DevOpsBot account	—	Needed for your API token

---

Installation

Choose the method that fits your setup. Option A (venv) is recommended for developers. Option B (system Python) works for everyone else and requires no extra steps.

---

Option A — Virtual environment (recommended for developers)

A virtual environment keeps the SDK isolated from your system Python.

Linux / macOS:

# Create and activate a venv
python3 -m venv devopsbot-env
source devopsbot-env/bin/activate

# Install via SSH
pip install "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

# OR install via HTTPS token
pip install "git+https://<YOUR_GITHUB_TOKEN>@github.com/consultancy-outfit/DevOpsBot-SDK.git"

Windows (Command Prompt):

python -m venv devopsbot-env
devopsbot-env\Scripts\activate

pip install "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

Windows (PowerShell):

python -m venv devopsbot-env
devopsbot-env\Scripts\Activate.ps1

pip install "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

The venv must be activated every time you open a new terminal before using agentos or running SDK scripts. You only create it once.

---

Option B — System Python (simplest, works for everyone)

Installs directly into your default Python environment — no activation needed.

Linux / macOS:

# via SSH
pip3 install --break-system-packages "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

# via HTTPS token
pip3 install --break-system-packages "git+https://<YOUR_GITHUB_TOKEN>@github.com/consultancy-outfit/DevOpsBot-SDK.git"

Windows:

# via SSH
pip install "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

# via HTTPS token
pip install "git+https://<YOUR_GITHUB_TOKEN>@github.com/consultancy-outfit/DevOpsBot-SDK.git"

--break-system-packages is required on Ubuntu 22.04+ and Debian 12+ due to PEP 668. It is safe — it only installs this package, it does not affect your system Python. Windows does not need this flag.

If pip is not found on Windows, use python -m pip install ... instead.

---

With optional collectors

Append [all] to either install command to enable screen capture and process listing:

Linux / macOS (system Python):

pip3 install --break-system-packages "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git[all]"

Linux / macOS (venv, after activation):

pip install "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git[all]"

Windows:

pip install "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git[all]"

---

Configure

Get your API token from DevOpsBot Web App → Settings → API Tokens → Generate Token. Token format: co_<uuid>_<32-hex-secret>

agentos configure

To replace an existing token:

agentos configure --rotate

---

Quick Start

import asyncio
from sdk import BackendClient

async def main():
    client = BackendClient.from_config()   # reads ~/.agentos/config.toml

    profile = await client.bootstrap()
    print(f"Logged in — tier: {profile.tier}")

    async for envelope in client.chat("my-thread", "What tasks are open?"):
        if envelope.type == "delta":
            print(envelope.data["text"], end="", flush=True)
        elif envelope.type == "done":
            print()
            break

asyncio.run(main())

---

Agents

The orchestrator runs AI agent pipelines server-side. You submit a task, receive a stream of progress envelopes, and approve or reject the outcome.

Run an agent

import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    req = OrchestratorRequest(
        task_input="hello",
        intent="greet",   # optional — helps the backend route the task
    )

    async for envelope in client.orchestrator_run(req):
        print(f"[{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            # Task needs a human decision before it continues
            task_id = envelope.data["task_id"]
            decision = input("Approve? (yes/no): ").strip().lower()
            await client.approve_task(
                task_id,
                decision="approved" if decision == "yes" else "rejected",
                note="Reviewed and approved by operator.",
            )

        elif envelope.type in ("done", "error"):
            break

asyncio.run(main())

Envelope types emitted by the orchestrator

Type	When it fires	Useful data
pipeline_started	Task accepted by backend	task_id
pipeline.<key>	A pipeline context field updated	key, value
awaiting_approval	Pipeline paused — human decision required	task_id
done	Pipeline completed	task_id, approval_status
error	Unrecoverable failure	code, message

List and approve tasks

import asyncio
from sdk import BackendClient

async def main():
    client = BackendClient.from_config()

    # List tasks waiting for approval
    result = await client.list_tasks(status="To Do", limit=20)
    for task in result.get("tasks", []):
        print(task["task_id"], task.get("summary", ""))

    # Approve a specific task by ID
    await client.approve_task("task-id-here", decision="approved", note="LGTM")

asyncio.run(main())

Test agents end-to-end (no repo clone needed)

Linux / macOS

python3 - << 'EOF'
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    print("Starting agent pipeline...")
    req = OrchestratorRequest(task_input="hello")

    async for envelope in client.orchestrator_run(req):
        print(f"  [{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            print("  → Auto-approving for test...")
            await client.approve_task(envelope.data["task_id"], decision="approved")

        elif envelope.type == "done":
            print("\nAgent completed successfully.")
            break

        elif envelope.type == "error":
            print(f"\nAgent error: {envelope.data}")
            break

asyncio.run(main())
EOF

Windows (PowerShell)

python - << 'EOF'
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    print("Starting agent pipeline...")
    req = OrchestratorRequest(task_input="hello")

    async for envelope in client.orchestrator_run(req):
        print(f"  [{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            print("  -> Auto-approving for test...")
            await client.approve_task(envelope.data["task_id"], decision="approved")

        elif envelope.type == "done":
            print("\nAgent completed successfully.")
            break

        elif envelope.type == "error":
            print(f"\nAgent error: {envelope.data}")
            break

asyncio.run(main())
EOF

Windows (Command Prompt)

Save as test_agent.py and run python test_agent.py:

# test_agent.py
import asyncio
from sdk import BackendClient
from sdk.models.requests import OrchestratorRequest

async def main():
    client = BackendClient.from_config()

    print("Starting agent pipeline...")
    req = OrchestratorRequest(task_input="hello")

    async for envelope in client.orchestrator_run(req):
        print(f"  [{envelope.type}] {envelope.data}")

        if envelope.type == "awaiting_approval":
            print("  -> Auto-approving for test...")
            await client.approve_task(envelope.data["task_id"], decision="approved")

        elif envelope.type == "done":
            print("\nAgent completed successfully.")
            break

        elif envelope.type == "error":
            print(f"\nAgent error: {envelope.data}")
            break

asyncio.run(main())

Expected output

Starting agent pipeline...
  [pipeline_started] {'task_id': 'tsk_abc123'}
  [pipeline.summary] {'key': 'summary', 'value': 'Processing...'}
  [awaiting_approval] {'task_id': 'tsk_abc123'}
  -> Auto-approving for test...
  [done] {'task_id': 'tsk_abc123', 'approval_status': 'approved'}

Agent completed successfully.

---

Error Handling

from sdk import BackendClient, TokenNotConfigured, BackendAuthFailed, BackendUnreachable

try:
    client = BackendClient.from_config()
    await client.ping()
except TokenNotConfigured:
    print("Run: agentos configure")
except BackendAuthFailed:
    print("Token expired — run: agentos configure --rotate")
except BackendUnreachable as e:
    print(f"Backend unreachable: {e}")

---

Upgrade

Linux / macOS (system Python):

pip3 install --break-system-packages --upgrade "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

Linux / macOS (venv — activate first):

source devopsbot-env/bin/activate
pip install --upgrade "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

Windows:

pip install --upgrade "git+ssh://[e-mail]/consultancy-outfit/DevOpsBot-SDK.git"

---

Uninstall

Remove the SDK package

Linux / macOS (system Python):

pip3 uninstall devops-bot-sdk -y

Linux / macOS (venv — activate first):

source devopsbot-env/bin/activate
pip uninstall devops-bot-sdk -y

Windows:

pip uninstall devops-bot-sdk -y

Remove the venv entirely (if you used one)

Linux / macOS:

rm -rf devopsbot-env

Windows (Command Prompt):

rmdir /s /q devopsbot-env

Windows (PowerShell):

Remove-Item -Recurse -Force devopsbot-env

Remove saved credentials

Deletes the stored token and backend URL from your machine.

Linux / macOS:

rm -rf ~/.agentos

Windows (Command Prompt):

rmdir /s /q %USERPROFILE%\.agentos

Windows (PowerShell):

Remove-Item -Recurse -Force $HOME\.agentos