Sessions

Audit trails are the foundation of AI agent governance -- they create cryptographic records to verify and prove every agent action for compliance and accountability. In the SDK, audit trails are managed through the Session class.

Creating Audit Trails

Start a session to create an audit trail for grouped actions:

python 
import asqav

asqav.init(api_key="sk_...")
agent = asqav.Agent.get("agent_abc123")

# Start a new session
session = agent.start_session()

print(f"Session ID: {session.session_id}")

Logging Actions

While a session is active, every sign() call on the agent is recorded to it:

python 
# Sign actions; each one is recorded to the active session
agent.sign("database:connect", {"host": "db.example.com"})
agent.sign("database:query", {"table": "users", "rows": 100})
agent.sign("api:openai:chat", {"model": "gpt-4", "tokens": 500})
agent.sign("storage:upload", {"file": "report.pdf", "size": 1024})

# End the session
agent.end_session()

Audit Trail States

State Description
active Session is running, can log actions
completed Session ended normally
error Session ended with an error
timeout Session expired without an explicit end

Retrieving Audit Trails

bash 
# Get a specific session
curl https://api.asqav.com/api/v1/sessions/ses_abc123 \
  -H "X-API-Key: sk_live_your_key"

# List sessions for an agent, with filters
curl "https://api.asqav.com/api/v1/sessions?agent_id=agt_abc123&session_status=completed&limit=10" \
  -H "X-API-Key: sk_live_your_key"

Viewing Actions

Retrieve all actions in a session:

python 
# Get all signed actions in the agent's current session
actions = agent.get_session_signatures()

# Or fetch any session by ID
actions = asqav.get_session_signatures("ses_abc123")

for action in actions:
    print(f"{action.signed_at}: {action.action_type}")
    print(f"  Signature: {action.signature_preview}")
    print(f"  Verify at: {action.verification_url}")

Verifying Audit Trail

Verify the integrity of a session's audit trail. All audit trails are protected by daily immutable proofs (Bitcoin-anchored via OpenTimestamps), ensuring tampering is detectable:

python 
# Rebuild the session timeline and re-verify the hash chain
timeline = asqav.replay("agt_abc123", "ses_abc123")

if timeline.verify_chain():
    print("Chain integrity verified")
    print(f"Actions: {timeline.total_actions}")

# Any single receipt is also publicly verifiable
result = asqav.verify_signature("sig_abc123")

Context Manager

Use sessions as context managers for automatic cleanup:

python 
with asqav.session() as sess:
    sess.sign("step:1", {"status": "started"})

    # Do some work...
    result = process_data()

    sess.sign("step:2", {"result": result})

# Session ends automatically when exiting the context.
# An unhandled exception signs a session:error record and
# marks the session status error before re-raising.

Reproducibility Metadata

sign() accepts dedicated parameters for the model and prompt context behind an action - the inputs needed to audit the exact conditions under which it was signed.

python 
# Attach model parameters and prompt hashes to the receipt
sig = agent.sign(
    "model:inference",
    {"model": "gpt-4"},
    model_name="gpt-4",
    model_params={"temperature": 0.2, "top_p": 1.0},
    system_prompt_hash="sha256:a1b2c3...",
    tool_inputs_hash="sha256:d4e5f6...",
)

These fields are signed into the audit trail alongside the action, so you can verify after the fact which model, parameters, and prompts produced a given decision. Useful for regulated deployments where you need to prove what was running at the time of a decision.

Compliance Bundle Export

Export a compliance bundle containing all audit trail data, signatures, and proofs for a given time range. The bundle is a self-contained archive that can be handed to auditors or uploaded to compliance platforms.

python 
# Package a session's signatures into a Merkle-rooted bundle
signatures = asqav.get_session_signatures("ses_abc123")
bundle = asqav.export_bundle(signatures, framework="eu_ai_act")

# Save the bundle
with open("compliance-bundle.json", "w") as f:
    f.write(bundle.to_json())

print(f"Bundle: {bundle.receipt_count} receipts")
print(f"Merkle root: {bundle.merkle_root}")

The bundle includes signed action logs, session records, policy snapshots, proof anchors, and a manifest with integrity hashes. Everything is cryptographically linked so tampering with any record invalidates the bundle.

Tip

Use compliance bundles with Compliance Reports to provide auditors with both the human-readable report and the underlying cryptographic evidence.

Audit Trail Replay

Replay an agent's complete action history as a timeline. Useful for incident investigation, compliance reviews, and debugging agent behavior after the fact.

python 
# Replay a session's audit trail
timeline = asqav.replay("agt_abc", "sess_abc123")
print(timeline.summary())

# Re-verify the hash chain across every step
assert timeline.verify_chain()

# Iterate through replayed actions
for step in timeline.steps:
    print(f"{step.timestamp}: {step.action_type} ({step.signature_id})")

The replay timeline preserves cryptographic signatures, so every replayed action can be independently verified against the original proof chain.

Trace Correlation

Link actions across multi-step workflows with a shared trace ID. Useful for debugging distributed agent pipelines and correlating audit trails across services.

python 
# Link actions across multi-step workflows
trace_id = asqav.generate_trace_id()
agent.sign("step:1", ctx, trace_id=trace_id)
agent.sign("step:2", ctx, trace_id=trace_id, parent_id="sig_prev")

All actions sharing a trace_id appear together in the audit trail, regardless of which agent or service produced them. The optional parent_id parameter establishes causal ordering between steps, so you can reconstruct the exact execution path during incident investigation.

Log Retention

Session logs are retained based on your tier:

Tier Retention
Free 30 days
Enterprise Custom
Tip

OpenTelemetry export for long-term storage in your own systems is available on all plans, including Free.

Audit Export

Raw audit export is available on all tiers, including Free. Use the Export button in the dashboard under Audit Trails to download signed action records as CSV or JSON, filtered by date range or agent. The same data is available programmatically via the GET /export/csv and GET /export/json API endpoints for automated pipelines. For a packaged compliance-grade archive with signatures and proofs bundled together, see Compliance Bundle Export above.

List and end sessions from the terminal with asqav sessions.