Metadata-Version: 2.4
Name: agent-operations-sdk
Version: 0.5.0
Summary: Open-source agent operations SDK — integration discovery, security scanning, autonomy rules, HITL primitives, and capability management for Python agentic systems.
Project-URL: Homepage, https://github.com/95percent-ai/agent-ops-sdk
Project-URL: Repository, https://github.com/95percent-ai/agent-ops-sdk
Project-URL: Issues, https://github.com/95percent-ai/agent-ops-sdk/issues
Project-URL: Changelog, https://github.com/95percent-ai/agent-ops-sdk/blob/main/CHANGELOG.md
Author-email: "95percent.ai" <inon@95percent.ai>
License: MIT License
        
        Copyright (c) 2026 95percent.ai
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent-ops,agents,autonomy,hitl,integration-discovery,llm,mcp,security-scanning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: agent-ops-sdk[deepagents,discover,hitl-butt-dial,langgraph]; extra == 'all'
Provides-Extra: deepagents
Requires-Dist: deepagents>=0.4; extra == 'deepagents'
Provides-Extra: dev
Requires-Dist: agent-ops-sdk[all]; extra == 'dev'
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: discover
Requires-Dist: beautifulsoup4>=4.12; extra == 'discover'
Requires-Dist: curl-cffi>=0.7; extra == 'discover'
Requires-Dist: jinja2>=3.1; extra == 'discover'
Requires-Dist: playwright>=1.48; extra == 'discover'
Provides-Extra: hitl-butt-dial
Requires-Dist: butt-dial-sdk>=0.1.0; extra == 'hitl-butt-dial'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Description-Content-Type: text/markdown

# 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)

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

Once published, just:

```bash
pip install agent-operations-sdk
```

## Quickstart

```python
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

| Module | Purpose |
|---|---|
| `agentops.registry` | Register / resolve / unregister integrations (MCP, OpenAPI, REST, local). |
| `agentops.security` | Schema + code + pattern scanning; quarantine for red flags. |
| `agentops.discover` | 12-tier integration discovery — HTTPS → TLS fingerprint → Playwright → cache relay. |
| `agentops.capability` | Capability generation, staging, test-before-publish with automated rollback. |
| `agentops.autonomy` | Rule-based decision engine with audit trail. |
| `agentops.runtime` | Agent-facing toolbelt + pluggable HITL channel. |
| `agentops.credentials` | Credential proxy — secrets never visible to agent code. |
| `agentops.worker` | Background task queue + health loops. |
| `agentops.agent.AgentTechDept` | Battery-included reference agent. |
| `agentops.integrations.langgraph` | First-class LangGraph nodes. |
| `agentops.integrations.deepagents` | deepagents wrapper. |
| `agentops.integrations.generic` | Framework-agnostic adapter. |
| `agentops.testing` | Fake MCP + fake target system + pytest fixtures for users' tests. |

## 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](LICENSE). Free for commercial use, no obligations.
