sdk-python

AegisAgent Python SDK

Client and @protect_tool decorator for AegisAgent — the integrity layer for AI agent actions.

The SDK is the enforcement point inside your agent's trust boundary. It:

• intercepts a protected tool call and authorizes it against the gateway,
• fails closed on deny, on action_hash mismatch (approve-then-swap), on an expired approval, and when the gateway is unreachable for a mutating/high-risk action,
• consumes single-use approvals atomically before executing (replay defense),
• ships a canonicalization scheme (aegis-jcs-1) that is byte-identical to the Rust gateway and the Go/TypeScript SDKs, so the hash a human approved is the hash that runs.

Install

pip install -e .            # from this directory
pip install -e ".[dev]"     # with black for formatting checks
pip install -e ".[async]"   # with httpx for the async client

Usage

Sync

from aegisagent import AegisClient, protect_tool

client = AegisClient(
    api_key="tenant_123",
    agent_id="coding-agent-prod",
    endpoint="http://127.0.0.1:8080",
)

@protect_tool(client=client, tool="github", action="merge_pull_request")
def merge_pr(repo: str, number: int) -> str:
    ...

Async

from aegisagent import AegisClient, async_protect_tool

client = AegisClient(
    api_key="tenant_123",
    agent_id="coding-agent-prod",
    endpoint="http://127.0.0.1:8080",
)

@async_protect_tool(client=client, tool="github", action="merge_pull_request")
async def merge_pr(repo: str, number: int) -> str:
    ...

If the gateway denies the action, PermissionError is raised and the wrapped function never runs. If a human approval is required, the call blocks until the approval is decided, then verifies the approved action hash matches the action about to execute before proceeding. On approval consume, the SDK also sends the current claimed_action_hash to the gateway so the single-use consume is atomically bound to the exact action.

CLI tools

# Verify a receipt chain
aegis-verify-receipts receipts.json

# Check gateway health and agent summary
aegis-status --gateway http://127.0.0.1:8080

# Freeze an agent
aegis-freeze-agent --gateway http://127.0.0.1:8080 --agent <id>

# Export audit events
aegis-export-audit --gateway http://127.0.0.1:8080 --output audit.json

Features

• AegisClient — sync client for all gateway endpoints (authorize, approvals, receipts, agents, SOC).
• AegisAsyncClient — async client powered by httpx (pip install aegisagent[async]).
• @protect_tool / @async_protect_tool — fail-closed decorators with approval polling + hash verification.
• Receipts — seal_receipt(), seal_chain(), verify_receipt(), verify_chain(), ReceiptAccumulator.
• Evidence packs — create_evidence_pack() for bundling receipts as compliance evidence.
• Webhook handling — WebhookHandler for approval callbacks, verify_slack_signature().
• Structured logging — StructuredJSONFormatter for JSON log output.
• SOC client methods — get_soc_summary(), list_alerts(), list_incidents(), close_incident(), narrate_incident().

Tests

python3 -m unittest discover -s tests   # 208 tests

See the main README and docs/action-receipt-spec.md for the full picture.

License

MIT — see LICENSE.