Governance in the SDK

Traccia SDKs support two levels of governance: trace evidence (works with any OTLP backend) and runtime policy enforcement (requires the Traccia platform).

observe vs govern

Runtime policy — govern

No [governance] section is needed in traccia.toml — policy URLs are derived from your tracing endpoint automatically.

from traccia import init, govern
from traccia.governance import AgentBlockedError

init(api_key="...", endpoint="https://api.traccia.ai/v2/traces")

@govern(agent_id="my-agent", fail_open=False, name="run_agent")
def run_agent(prompt: str) -> str:
    return call_llm(prompt)

Trace evidence — disclosure

Record EU AI Act Art. 50 transparency on the active span after your UI shows an AI notice. Works with observe — no platform policy API involved.

from traccia.governance import disclosure

disclosure(channel="ui", disclosed_to_user=True)

HIPAA-oriented init

Opt into HIPAA-oriented span attributes and prefer redaction when agents may touch ePHI. Soft warnings only — the SDK does not block PHI. Traccia does not currently offer a signed BAA. Platform workflow: HIPAA Controls for AI Agents.

from traccia import init, observe

init(
    compliance={"frameworks": ["hipaa"]},
    redact_pii=True,
)

@observe()
def clinical_assistant(user_message: str) -> str:
    return f"Acknowledged: {user_message[:200]}"

Advanced: custom policy endpoints

Only needed for non-standard deployments. Defaults: {base}/api/v1/agents/{agent_id}/status and .../blocks.

[governance]
status_check_endpoint = "https://custom.example/agents/{agent_id}/status"
post_block_endpoint = "https://custom.example/agents/{agent_id}/blocks"
status_cache_ttl_seconds = 120