Skip to content
TapPass

Understanding the output

Every governed call returns more than the model’s text. This page annotates real response shapes so you know what you’re looking at — in the SDK, in the raw API, and in the dashboard.

An allowed call (SDK)

Section titled “An allowed call (SDK)”
response = agent.chat("Summarize Q4 revenue")
response.content                  # the assistant's answer
response.pipeline.blocked         # False
response.pipeline.classification  # "INTERNAL" — data classification of the call
response.pipeline.steps_run       # how many checkpoints ran
response.pipeline.total_duration_ms
response.usage.total_tokens       # 157
response.session_id               # "ses_…"  ─┐
response.task_id                  # "tsk_…"   │ five correlation IDs —
response.agent_uuid               #           │ every one is queryable
response.pipeline_uuid            #           │ in the audit API
response.audit_url                # dashboard deep-link to this exact call

The five correlation IDs are the important part. Any question — why was this allowed? what did it cost? what else happened in this session? — starts from one of these.

An allowed call (raw API)

Section titled “An allowed call (raw API)”

Same call through the gateway:

{
  "choices": [{"message": {"role": "assistant", "content": "…"}}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 145, "total_tokens": 157},
  "tappass": {
    "session_id": "ses_abc123",
    "task_id": "tsk_…",
    "audit_url": "https://app.tappass.ai/audit/…",
    "blocked": false
  }
}

The tappass envelope is added to the standard provider response. The gateway always returns HTTP 200 — governance outcomes are data, not HTTP errors.

A blocked call

Section titled “A blocked call”
from tappass import PolicyBlockError


try:
    agent.chat("List all customer credit card numbers")
except PolicyBlockError as e:
    e.blocked_by      # the rule/step that decided, e.g. a BlockPII rule
    e.reason          # machine-readable reason, e.g. "pii_in_input"
    e.classification  # "RESTRICTED"
    e.audit_url       # the blocked attempt is in the audit trail too

Through the raw API, a block arrives as an assistant message explaining the block, with tappass.blocked: true. Your agent reads it like any other refusal — it never crashes on governance.

Three things to internalize:

  1. Blocked attempts are audited. The trail records what was tried, what fired, and the full evidence — that’s your incident queue.
  2. The reason names a rule. e.blocked_by deep-links to the exact rule and policy version. If the block is wrong, the fix is a policy change — not a code change.
  3. Don’t retry blindly. Retrying an identical request under an unchanged policy yields the same decision — retrying blindly won’t get a different answer.

A redacted call

Section titled “A redacted call”

Policy can allow a call while changing it — the redact obligation masks PII/secrets in place:

response = agent.chat("Email a summary to jane@acme.com")
response.content        # clean answer; the call went through

By default, redaction is invisible: the call succeeds with clean content. Set Agent(raise_on_redaction=True) to surface it as a RedactionApplied exception carrying the exact spans (redactions: list[Redaction], redacted_content).

An approval pause

Section titled “An approval pause”

A RequireApproval rule doesn’t block — it suspends:

from tappass import ApprovalRequired


try:
    agent.chat("Wire €50,000 to supplier 881")
except ApprovalRequired as e:
    e.approval_url   # dashboard deep-link for the human


```python
result = agent.wait_approval(e.request_id, timeout_seconds=300)
result["state"]   # "approved" | "denied" | "timed_out" | "cancelled"

One approval authorizes exactly the fingerprinted action. Resubmitting the identical call passes; a different amount starts a new approval.

In the dashboard

Section titled “In the dashboard”
What you got Where to look
audit_url Opens the exact event in Audit Trail
session_id Sessions → full trace with spans and applied rules
blocked_by / rule id Policies → the owning policy and version
Approval request Bell icon → Approvals inbox
Anything odd Command Center → “Recent flagged events”

Next steps

Section titled “Next steps”