agent-operations-sdk

Give Python agents the ability to operate real organization systems — CRMs, WMSes, email, databases, admin consoles, arbitrary web apps — with onboarding-time integration discovery, security scanning, autonomy rules, human-in-the-loop primitives, and test-before-publish staging.

Status: Alpha (0.1.0, in development). Extracted from iv-bknd's AT (Agent Technology Department) agent, consolidating patterns from skill-builder, nanoclaw, and mcp-tester. Pre-release — see docs/TODO.md.

Why this exists

Every agent framework needs to let agents do things in the real world. Building that safely means solving nine hard problems simultaneously:

1. Discover how to talk to a system (API? scraper? browser?)
2. Generate a working client
3. Scan it for dangerous patterns
4. Register it as agent-callable tools
5. Permission-gate who can use what
6. Pause the agent and ask a human when needed
7. Escalate high-risk actions to HITL
8. Roll back when something breaks
9. Audit every decision for later

This SDK bundles all nine. One install, one configuration, done.

Install (pre-release)

pip install -e 'git+https://github.com/95percent-ai/agent-operations-sdk.git#egg=agent-operations-sdk[all]'

Once published, just:

pip install agent-operations-sdk

Quickstart

import asyncio
from agentops.agent import AgentTechDept
from agentops.runtime import MemoryChannel, ToolOutcome
from agentops.credentials import Credential
from agentops.credentials.store import AuthType

async def main():
    # 1. Spin up the ops agent — one line, everything wired up
    at = AgentTechDept(channel=MemoryChannel())
    await at.load_default_policy()  # reads allowed, writes ask, rest deny

    # 2. Register an integration (auto-scans for security)
    status = await at.register_remote(
        name="crm",
        url="https://crm.example.com/sse",
        token="...",
    )
    # status is IntegrationStatus.GREEN / AMBER / RED / PENDING

    # 3. Store credentials so the agent doesn't see tokens
    await at.credentials.store.put(
        "crm", Credential("real-token", auth_type=AuthType.BEARER, system="crm"),
    )

    # 4. Grant an agent scoped access
    await at.assign("sales-bot", "crm", allowlist=["get_contact", "create_order"])

    # 5. Hand the agent a Toolbelt; executor is YOUR business logic
    async def executor(qualified, params):
        # Use at.credentials.authorized_client("crm") or your own dispatch
        return {"ok": True, "called": qualified}

    tools = at.for_agent("sales-bot", executor=executor)

    # 6. Agent calls tools — autonomy gate + HITL + audit automatic
    r = await tools.execute_capability("crm.get_contact", params={"id": "C-1"})
    assert r.outcome == ToolOutcome.OK

asyncio.run(main())

See examples/minimal/autonomy_hitl.py for a complete runnable version showing all four decision outcomes (ALLOW / ASK / HITL / DENY) with a 3-layer policy.

Components

Design principles

• Extract, don't copy. Patterns from production (AT, skill-builder, nanoclaw) are ported with added tests that prove real behavior.
• No mockup success. Every feature has at least one test that exercises it against a realistic fake server and asserts on observable behavior — not "function returned True."
• Rollback-first. Any state-modifying action can be reverted.
• Credentials never cross the agent boundary. Proxy injects auth; agent code cannot read secrets.
• Autonomy is data. Rules are readable, editable, auditable — never hardcoded.
• Security as a layer, not a feature. Every registration / generation / assignment passes through Scanner.

License

MIT. Free for commercial use, no obligations.