criticalbridge

Python SDK for building governed external agents on CriticalBridge. Boots the conformance sidecar in-process via subprocess, dispatches A2A /tasks to your handlers, and auto-emits decision lineage to the Brain. The Python side of the integration described in the External Agent Integration Guide.

Install

pip install criticalbridge

v0.1 requires Node.js (>=20) on PATH — the SDK spawns the TypeScript sidecar (@criticalbridge/conformance-sidecar) as a subprocess via npx. v0.2 will ship a standalone binary that removes this dependency.

Hello-world agent

import os
from criticalbridge import ManagedAgent

agent = ManagedAgent(
    brain_base_url="https://api.criticalbridge.ai",
    enrollment_token=os.environ["CB_ENROLLMENT_TOKEN"],
    entity_id="acme-corp",
    agent_id="customer-support-langchain-v2",
    vendor="langchain",
    public_url="https://sidecar.acme.example.com",   # HTTPS, what the Brain dispatches to
)

agent.start()  # boots the sidecar; blocks until /healthz green

@agent.handler("customer.read")
def lookup_customer(request, context):
    # business logic — call your model, your CRM, whatever
    customer = {"id": request["customer_id"], "name": "Sample"}
    return agent.respond(
        action="return_customer_info",
        payload=customer,
        model_invocation={"model": "gpt-4o", "promptTokens": 412, "completionTokens": 87},
        risk_tier="low",
    )

agent.serve()  # blocks until SIGINT

What the SDK gives you

Sidecar lifecycle — spawn, wait-for-ready, graceful teardown on SIGINT / atexit
/tasks dispatcher — local HTTP server, routes A2A envelopes to the right @handler
respond() — builds the A2A response AND queues a decision-lineage emit (NAIC V2 wire shape via cb-conformance)
Live session — agent.session reads the registration JWT fresh from the sidecar each time (so E2 token refreshes are picked up without a restart)

Configuration

ManagedAgent(...) accepts these kwargs (validated at construction time; bad config raises BadConfigError before any I/O):

Field	Required	Notes
`brain_base_url`	yes	e.g. `https://api.criticalbridge.ai`
`entity_id`	yes	Your CriticalBridge entity
`enrollment_token`	yes	One-time token from Portal `/dashboard/managed-agents/enrollment-tokens`
`agent_id`	yes	Durable per-agent ID within the entity
`vendor`	no	One of `langchain` / `autogen` / `crewai` / `semantic-kernel` / `haystack` / `other`. Default `other`.
`public_url`	no	HTTPS URL the Brain dispatches to the sidecar. Required for production deploys.
`sidecar_port`	no	Sidecar's listen port (default 8080)
`local_port`	no	Local /tasks server port (default ephemeral)
`display_name`	no	Label in the Portal fleet view
`capability_tags`	no	List of capability strings

Logging

import logging
logging.getLogger("criticalbridge").setLevel(logging.DEBUG)         # everything
logging.getLogger("criticalbridge.sidecar").setLevel(logging.WARNING)  # quiet sidecar passthrough

Set CB_LOG_LEVEL=DEBUG in the environment as a shortcut.

License

Apache-2.0 © Frank Burkitt and CriticalBridge.AI contributors.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

criticalbridge-1.0.2.tar.gz (55.2 kB view details)

Uploaded Jul 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

criticalbridge-1.0.2-py3-none-any.whl (58.6 kB view details)

Uploaded Jul 12, 2026 Python 3

File details

Details for the file criticalbridge-1.0.2.tar.gz.

File metadata

Download URL: criticalbridge-1.0.2.tar.gz
Upload date: Jul 12, 2026
Size: 55.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for criticalbridge-1.0.2.tar.gz
Algorithm	Hash digest
SHA256	`ff0183422e8e0e1d909419921881c5057a6b3277b031461ae6b2f5d11f461949`
MD5	`e6c6388efa8df9317ef9de0797bb6fe9`
BLAKE2b-256	`34fea8d25ff3e14d31518ebd0ea863d802fd91a2c87e8963c3b94972b1423134`

See more details on using hashes here.

Provenance

The following attestation bundles were made for criticalbridge-1.0.2.tar.gz:

Publisher: publish-criticalbridge-sdk.yml on fburkitt/CriticalBridgeApp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: criticalbridge-1.0.2.tar.gz
- Subject digest: ff0183422e8e0e1d909419921881c5057a6b3277b031461ae6b2f5d11f461949
- Sigstore transparency entry: 2150811091
- Sigstore integration time: Jul 12, 2026
Source repository:
- Permalink: fburkitt/CriticalBridgeApp@95860bb220ae89f337f932e0858496387bfd26b0
- Branch / Tag: refs/tags/criticalbridge-v1.0.2
- Owner: https://github.com/fburkitt
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-criticalbridge-sdk.yml@95860bb220ae89f337f932e0858496387bfd26b0
- Trigger Event: push

File details

Details for the file criticalbridge-1.0.2-py3-none-any.whl.

File metadata

Download URL: criticalbridge-1.0.2-py3-none-any.whl
Upload date: Jul 12, 2026
Size: 58.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for criticalbridge-1.0.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`ba0218632241c624b39ee99f9aa9487f821f9e1dd96b40229f5ad92c9781b83f`
MD5	`de7aa1ed3744cb222a8f0c5914e8a734`
BLAKE2b-256	`2365694e4c0010b513c4fa4eea035f3e7193dbc1c281f10d3806f278aeace34b`

See more details on using hashes here.

Provenance

The following attestation bundles were made for criticalbridge-1.0.2-py3-none-any.whl:

Publisher: publish-criticalbridge-sdk.yml on fburkitt/CriticalBridgeApp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: criticalbridge-1.0.2-py3-none-any.whl
- Subject digest: ba0218632241c624b39ee99f9aa9487f821f9e1dd96b40229f5ad92c9781b83f
- Sigstore transparency entry: 2150811274
- Sigstore integration time: Jul 12, 2026
Source repository:
- Permalink: fburkitt/CriticalBridgeApp@95860bb220ae89f337f932e0858496387bfd26b0
- Branch / Tag: refs/tags/criticalbridge-v1.0.2
- Owner: https://github.com/fburkitt
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-criticalbridge-sdk.yml@95860bb220ae89f337f932e0858496387bfd26b0
- Trigger Event: push

Release history Release notifications | RSS feed

This release

1.0.2 This release

Jul 12, 2026 2 files

1.0.1

Jun 30, 2026 2 files

1.0.0

Jun 30, 2026 2 files

0.0.1

Jun 29, 2026 2 files

criticalbridge 1.0.2

criticalbridge

Install

Hello-world agent

What the SDK gives you

Configuration

Logging

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed