SDKs

Contro1 Python SDK

Install and use the official Contro1 Python SDK to create approval requests, verify signed webhooks, log autonomous actions, and fetch audit evidence.

Use the centcom Python package when your agent runtime, backend service, or workflow worker runs in Python.

Use the integration skill

Copy this skill link into your code agent to add Python SDK and Contro1 to your system.

Copy skill link

Key takeaways

  • Install the SDK with pip install centcom.
  • Use create_protocol_request when an action must pause for human approval.
  • Use log_action for allowed autonomous actions that still need durable evidence.
  • Verify signed webhooks before resuming any production action.

Install

Use the Python SDK when your agent, service, worker, or webhook bridge is written in Python. The same client handles approval requests, audit records, read APIs, and webhook verification helpers.

terminal
pip install centcom
.env
CENTCOM_API_KEY=cc_live_your_key
CENTCOM_BASE_URL=https://api.contro1.com/api/centcom/v1
CENTCOM_WEBHOOK_SECRET=whsec_your_secret

Initialize the client

contro1_client.py
import os
from centcom import CentcomClient

client = CentcomClient(
    api_key=os.environ["CENTCOM_API_KEY"],
    base_url=os.environ.get("CENTCOM_BASE_URL"),
)

Create an approval request

Call create_protocol_request at the point where a risky action is ready but has not executed yet. Use external_request_id for idempotency and correlation_id to group the full business case.

approval_request.py
request = client.create_protocol_request({
    "title": "Approve vendor transfer?",
    "request_type": "approval",
    "source": {"integration": "finance-agent", "workflow_id": "vendor-payment", "run_id": run_id},
    "routing": {"required_role": "finance", "priority": "urgent", "sla_minutes": 10},
    "context": {
        "action_type": "send_payment",
        "resource": "vendor:atlas-ltd",
        "summary": "New vendor bank account. Invoice INV-9821. Amount $52,400.",
    },
    "risk_level": "high",
    "policy_trigger": "Payments above $10,000 require finance approval.",
    "approval_comment_required": True,
    "continuation": {"mode": "decision", "webhook_url": "https://agent.example.com/webhooks/contro1"},
    "external_request_id": f"vendor-payment:{run_id}:atlas-transfer",
    "correlation_id": f"case_vendor_payment_{run_id}",
})

Verify the webhook

Webhook-first is the production path. Verify the signature and timestamp before trusting status, reviewer comments, or structured response data.

webhook.py
from centcom import verify_webhook

ok = verify_webhook(raw_body, signature, timestamp, os.environ["CENTCOM_WEBHOOK_SECRET"])
if not ok:
    raise PermissionError("Invalid Contro1 webhook signature")

if payload["status"] != "approved":
    abort_action()
else:
    resume_action(payload["response"])

Log autonomous actions

Approval requests already store the human decision. Use log_action for actions that were allowed to run automatically but still need searchable evidence.

audit_record.py
client.log_action(
    action="report.archived",
    summary="Moved quarterly report from staging to approved archive folder.",
    source={"integration": "document-agent", "workflow_id": "archive-flow", "run_id": run_id},
    outcome="success",
    severity="info",
    correlation_id=case_id,
)

Fetch evidence

request_evidence.py
evidence = client.get(f"/requests/{request_id}/evidence")
case_timeline.py
timeline = client.get(f"/cases/{case_id}")

Send full agent traceability

Beyond the approval call, attach identity, a run trace, the tools you invoked, and the context you retrieved. Each field is optional — add what you have. The verified identity always comes from your API key; a caller-supplied actor.agent_id is recorded as a claimed sub-agent until an admin verifies it.

  • trace_id / parent_trace_id — link one run (and sub-agent runs) into a single trace.
  • tool_calls[] — what the agent tried to do, so reviewers see the actions.
  • retrieved_context[] — the data the decision was based on (RAG provenance).
  • Then export a signed evidence packet from GET /requests/:id/evidence.
Send full traceability
# Same approval call you already make — now with full traceability.
client.requests.create(
    request_type="approval",
    title="Refund $4,200 to customer 8831",
    source={"integration": "api"},
    actor={"agent_id": "billing-agent", "agent_name": "Billing Agent"},  # claimed sub-agent
    trace_id=f"trc_{run_id}",          # link every step of this run
    tool_calls=[{"name": "lookup_order", "outcome": "success"}],
    retrieved_context=[{"source": "policy:refunds", "uri": "kb://policy/refunds"}],
    continuation={"mode": "decision"},
)

Agent identity, traceability & signed evidence

Frequently asked questions

When should I use the Python SDK instead of a framework connector?

Use the Python SDK for custom Python services, workers, and agents. Use a framework connector when you are inside LangGraph, CrewAI, OpenAI Agents SDK, or another supported runtime with its own pause/resume pattern.

Do approval requests automatically create evidence?

Yes. The request stores context, routing, decision, reviewer, timestamps, callback state, and protocol response. Use audit records for additional autonomous or post-approval events.