PRISM Documentation

Introduction

What PRISM Does

PRISM is an observability platform for AI agents. Your application sends PRISM a record of each exchange it has with a model. PRISM stores that record, scores it automatically, groups it into conversations and runs, watches it for the failures you care about, and tells you when something changes.

Everything starts from one HTTP call. Frameworks, the SDK, and the proxy are conveniences layered on top of it, so no integration path can do something the API cannot.

Core Concepts

Quickstart

Create an account at prism.blockconvey.com/signup. Signing up creates your organization and your first project. No invitation is needed.

1. Get Your Credentials

You need three values. Take the project ID from Settings → Project, and create a key on the API keys page.

# .env  --  never commit this file
PRISMTRACE_HOST=https://prism.blockconvey.com
PRISMTRACE_PROJECT_ID=00000000-0000-0000-0000-000000000000
PRISMTRACE_API_KEY=pt-sk-...

echo '.env' >> .gitignore

2. Send a Trace

Every integration eventually does this. Run it once from your terminal to prove the credential works before wiring anything into your application.

curl -sS -X POST "$PRISMTRACE_HOST/api/traces" \
  -H "Content-Type: application/json" \
  -H "X-PRISMtrace-Key: $PRISMTRACE_API_KEY" \
  -d '{
    "project_id":     "'"$PRISMTRACE_PROJECT_ID"'",
    "model":          "claude-sonnet-4-6",
    "input_messages": [{"role": "user", "content": "What loan rates do you offer?"}],
    "output_message": "Our personal loan rates currently start at 7.9% APR.",
    "latency_ms":     420,
    "session_id":     "conversation-1",
    "agent_id":       "loan-assistant"
  }'

A 200 returns the stored trace, including its id and computed cost_usd. Open Traces and it is there.

3. Confirm It Landed

An empty dashboard has several possible causes that look identical from the outside. Connection health tells them apart, and the same information is available over the API.

Programmatically:

curl -sS "$PRISMTRACE_HOST/api/setup-doctor?project_id=$PRISMTRACE_PROJECT_ID" \
  -H "X-PRISMtrace-Key: $PRISMTRACE_API_KEY"

Read live_connected and blocked_step. From a Python project, python -m prismtrace.verify does the same thing.

Integrations

Choosing a Path

Three ways in. You need one.

Python SDK

The distribution is prismtrace-sdk; the import package is prismtrace. Install one, import the other.

pip install "prismtrace-sdk>=0.4.0"

LangChain

import os
from prismtrace import PRISMtraceCallbackHandler
from langchain_anthropic import ChatAnthropic

handler = PRISMtraceCallbackHandler(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    host=os.environ["PRISMTRACE_HOST"],
    agent_name="loan-assistant",
    session_id="conversation-1",   # one value per conversation
)

llm = ChatAnthropic(model="claude-sonnet-4-6", callbacks=[handler])
# ... run your chain or agent ...
handler.flush()

LangGraph — wrap_langgraph injects the callbacks on invoke and stream, so you do not repeat the config at every call site.

import os
from prismtrace import PRISMtraceLangGraphHandler, wrap_langgraph

handler = PRISMtraceLangGraphHandler(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    host=os.environ["PRISMTRACE_HOST"],
    agent_name="my-graph",
    session_id="graph-run-1",
)

graph = wrap_langgraph(compiled_graph, handler)
graph.invoke({"messages": [("user", "hello")]})
handler.flush()

Google ADK — multi-agent handoffs are recorded as handoff steps, so delegation between sub-agents shows in the trajectory instead of collapsing into one opaque run.

import os
from prismtrace import PRISMtraceADKAdapter
from google.adk.agents import LlmAgent

adapter = PRISMtraceADKAdapter(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    agent_name="my-adk-agent",
)

agent = LlmAgent(
    model="gemini-2.0-flash",
    instruction="You are a helpful assistant.",
    before_model_callback=adapter.before_model,
    after_model_callback=adapter.after_model,
    before_tool_callback=adapter.before_tool,
    after_tool_callback=adapter.after_tool,
    before_agent_callback=adapter.before_agent,
    after_agent_callback=adapter.after_agent,
)

LiteLLM — one call at startup traces every model LiteLLM routes to, through a single hook.

import os, litellm
from prismtrace import install_litellm

install_litellm(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
)

response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "hello"}],
)

OpenAI Agents SDK

import os
from agents import Agent, Runner
from prismtrace import install_openai_agents

install_openai_agents(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
)

agent = Agent(name="my-agent", instructions="...")
result = await Runner.run(agent, "hello")

TypeScript and JavaScript

Instrument your chat handler, or the completion callback of generateText / streamText, so each turn emits one trace. On serverless, await the call so the function is not frozen mid-request.

const HOST = process.env.PRISMTRACE_HOST!;
const API_KEY = process.env.PRISMTRACE_API_KEY!;
const PROJECT_ID = process.env.PRISMTRACE_PROJECT_ID!;

export async function emitTrace(
  input: string,
  output: string,
  opts: { model: string; latencyMs: number; sessionId?: string },
) {
  const res = await fetch(HOST + "/api/traces", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-PRISMtrace-Key": API_KEY,
    },
    body: JSON.stringify({
      project_id: PROJECT_ID,
      model: opts.model,
      input_messages: [{ role: "user", content: input }],
      output_message: output,
      latency_ms: opts.latencyMs,
      session_id: opts.sessionId,
    }),
  });
  if (!res.ok) {
    throw new Error("PRISM ingest " + res.status + ": " + (await res.text()));
  }
}

Zero-Code Proxy

Point your existing provider client at PRISM instead of the provider. Nothing is imported and no call site changes. PRISM forwards the call, records it, and runs your guardrails in both directions. It adds one network hop, roughly 5 to 15 ms depending on region.

Three providers are proxied. Each client wants the base URL in a slightly different shape.

import anthropic, os

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://prism.blockconvey.com/proxy/anthropic",
    default_headers={"X-PRISMtrace-Key": os.environ["PRISMTRACE_API_KEY"]},
)

# OpenAI  ->  base_url="https://prism.blockconvey.com/proxy/openai/v1"
# Gemini  ->  client_options={"api_endpoint": "https://prism.blockconvey.com/proxy/gemini"}

Azure AI Foundry uses the OpenAI proxy route with your resource passed as an x-azure-endpoint header. AWS Bedrock does not use the proxy: it connects with stored AWS credentials from the Connectors page.

Voice Agents

A voice agent has no LLM call site to wrap, so PRISM hooks the voice platform. Each ElevenLabs call becomes one trajectory: caller speech is a speech-to-text step, the agent reply is a text-to-speech step. Transcripts are scrubbed for PII on the server before storage, and audio is never sent to or stored by PRISM.

• Post-call webhook. No code. Point ElevenLabs at the webhook URL on the

connector card and subscribe to post_call_transcription only. Do not enable post_call_audio; PRISM rejects it. Store the ElevenLabs signing secret on the connector so deliveries are verified against your project.

• Live tracing. Calls appear while they are still in progress.

import os
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
from prismtrace import PRISMtraceVoiceTracer

tracer = PRISMtraceVoiceTracer(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    agent_name="Support line",
)

conversation = Conversation(
    ElevenLabs(api_key=os.environ["ELEVENLABS_API_KEY"]),
    AGENT_ID,
    requires_auth=True,
    audio_interface=DefaultAudioInterface(),
    **tracer.callbacks(),
)

conversation.start_session()
tracer.finalize(conversation.wait_for_session_end())

Warehouses and Export

Connect Snowflake or Databricks from the Connectors page with stored warehouse credentials, then sync on demand. Data Export downloads traces, scores, annotations, conversations, and alerts as CSV. Import Traces back-fills history from an existing log so you are not starting from an empty dashboard.

API Reference

Base URL: https://prism.blockconvey.com

Authentication

Machine callers authenticate with the X-PRISMtrace-Key header. This is not a bearer token: Authorization: Bearer carries dashboard sessions and will be rejected for an API key.

X-PRISMtrace-Key: pt-sk-...

Keys carry scopes. Give an application only what it needs.

A key can be rotated with a grace period, so the old one keeps working while you roll out the new one, then revoked. Both are on the API keys page.

Create a Trace

POST https://prism.blockconvey.com/api/traces

{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "model": "claude-sonnet-4-6",
  "input_messages": [
    { "role": "user", "content": "What loan rates do you offer?" }
  ],
  "output_message": "Our personal loan rates currently start at 7.9% APR.",
  "latency_ms": 420,
  "token_count_input": 45,
  "token_count_output": 180,
  "session_id": "conversation-1",
  "user_identifier": "user-4521",
  "agent_id": "loan-assistant",
  "agent_name": "Loan Assistant",
  "metadata": { "source": "production" }
}

Returns 200 with the stored trace: its id, the resolved cost_usd, and the session_id it was filed under.

Diagnostics

Usage and Credits

Errors and Limits

Platform

Traces, Sessions, and Runs

Click any trace for the full conversation, the automatic analysis, the trajectory steps, and any guardrail flags. Above the list, Sessions groups traces sharing a session_id so a conversation reads end to end, and Agent Runs shows the trajectory inside a single run: which model was called, which tools fired, where a handoff happened, and where it failed.

Model Inventory fills itself from the agent_id and model on your traces. There is nothing to register by hand; send a trace and the agent appears, with trace count, average latency, last activity, and provider. Sending a stable agent_id is what stops one agent splitting into several entries.

Automatic Scoring

Every trace is analysed on arrival. This costs no credits and happens whether or not you ask for it.

PRISM also detects the industry of a conversation and applies extra checks on top: rate promises and regulated-activity flags for financial conversations, PHI exposure and unsafe medical advice for healthcare, and privilege risk for legal.

Guardrails

Every rule has an action, flag or block, and takes effect on save with no deployment step. Ten rule types are available.

Where to start

1. PII / PHI on flag. Watch what it catches on your own traffic for a few days, then switch to block once you trust it.
2. Prompt Injection on block. There is no legitimate reason for a user to override your agent instructions.
3. Secrets Detection on block if your agent can see configuration, infrastructure, or code.

Alerts

A rule is a metric, a condition, a threshold, and a severity, optionally scoped to one agent. Give it a notification email and PRISM writes there when the rule fires. Fired alerts can be resolved or dismissed, and repeated firings are grouped into patterns so a recurring problem reads as one thing rather than forty. Alerts are available on Free and Builder alike.

Root Cause and Remediation

Root Cause clusters failing traces into recurring problems and traces each back toward the prompt or code responsible, rather than leaving you to read failures one at a time. Remediation turns those clusters into concrete recommendations. Agent Intelligence sits above both, summarising a window of traffic in prose and naming the failure themes inside it.

Plans and Credits

Two separate things govern what your account can do. Plan limits are capacity: how much you can store and for how long. Credits meter the AI actions you deliberately trigger. Neither ever hides data you have already captured.

Free and Builder

Free is the complete core product, not a trial. Traces, sessions, agent runs, automatic scoring, alerts, root cause, remediation, Knowledge Base, Model Inventory, connectors, and export all work on Free. Builder raises the ceilings and adds three capabilities: Guardrails, the Evaluators Hub with its annotation queues, and the expanded Model Inventory.

Live usage against each limit, and how each one is actually applied, is on Settings → Billing and usage, or over the API at GET /api/entitlements/usage.

Credits

A credit is the unit for AI work you ask PRISM to perform. Your plan grants an allowance once per rolling 30-day cycle, anchored to the date your organization was created rather than to the calendar month, so your cycle renews on your own date. New organizations also get a one-time welcome grant of 100 credits, and top-up packs of 100 can be bought at any time. Unused allowance carries over up to one full allowance, so an idle account does not accumulate indefinitely.

Free

Anything the platform does on its own. Trace ingest, viewing traces, the automatic per-trace analysis and its scores, trajectory assembly, regulatory classification, Knowledge Base processing, guardrail checks, dataset and evidence exports, and the onboarding and integration assistants. Free allows 25,000 traces against a 100-credit allowance, so metering automatic analysis would exhaust a cycle before you had taken a single action.

Metered

Actions you deliberately trigger. Prices follow one ladder: 1 for a single judgement, 2 for a recommendation, 5 for a multi-pass or report-sized job.

At a zero balance

New AI actions pause, and nothing else does. Trace capture continues within your plan limits, existing data stays fully readable, automatic per-trace analysis keeps running, and guardrails and alerts keep working. An action you cannot afford returns 402 with the price and your balance, so your own tooling can handle it. There is no automatic overage and no auto top-up: the balance cannot go below zero without you buying more.

Security

• Keys live in the environment. A .env file locally, your platform secret

manager in production. Never hardcode a key, never commit one.

• Send the key as a header. Use X-PRISMtrace-Key. The deprecated body field

puts your credential into request logs and payload captures.

• Use the narrowest scope. An application that only sends traces should carry

an ingest key. It cannot then read your data back or spend credits.

• Rotate, do not swap. Rotation issues a new key while the old one keeps

working for a grace period. Roll out, then revoke.

• One project per environment. Dev, staging, and production each get their own

project and keys, so revoking one never touches the others.

• Keys are shown once. PRISM stores only a hash. If a key is lost, rotate it.
• Voice audio is never stored. ElevenLabs transcripts are PII-scrubbed

server-side before storage, and audio is never sent to PRISM at all.

Troubleshooting

Reference

PRISM agent integration brief

You are a coding agent working inside an application repository. Your job is to wire live tracing into PRISM so sessions, model calls, tool use, errors and latency appear in the PRISM dashboard.

Read this document fully before editing. Propose a plan, then make the smallest change that emits real traces.

Non-negotiables

• Authenticate with the header X-PRISMtrace-Key. This is not a bearer token. Authorization: Bearer carries dashboard sessions and will 401 an API key.
• Do not invent credentials, project ids or hosts. Use exactly the values the operator supplies.
• Do not install an npm package. None exists. For JavaScript and TypeScript, POST to the HTTP endpoint.
• Do not commit secrets. .env stays untracked; put key names only in .env.example.
• Do not report success from a handshake alone. A handshake proves a credential, not an integration.
• Do not point production traffic at an unverified setup without explicit approval. Instrument staging first.
• Editing files is not the deliverable. A trace arriving in PRISM is.

Required inputs

If any is missing, stop and ask. Do not guess and do not read them out of an unrelated service.

Step 1: choose a path

Choose from repository evidence, not from what the operator says the stack is. Grep the repository. Take the first rule that fires.

AWS Bedrock is none of these. It connects with AWS credentials stored in the PRISM dashboard, not from application code.

Do not run pip install in a repository that contains no Python.

Step 2: instrument

Symbols that exist

Import these from prismtrace. The distribution is prismtrace-sdk; the import package is prismtrace. They differ on purpose.

Symbols that do not exist

Do not write any of these. Each has been produced by a model before, and each fails on the import line.

• PRISMtraceLangchainCallback — the export is PRISMtraceCallbackHandler
• @prismtrace/sdk, prismtrace-js, or any npm package
• monitor(), wrap_bedrock(), or a blockconvey module
• prism-sdk or prismsdk as the pip distribution — it is prismtrace-sdk
• An OpenTelemetry ingest endpoint. /api/otlp/v1/traces is not served.

Install

pip install "prismtrace-sdk>=0.4.0"

LangChain

import os
from prismtrace import PRISMtraceCallbackHandler

handler = PRISMtraceCallbackHandler(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    host=os.environ["PRISMTRACE_HOST"],
    agent_name="my-agent",
    session_id="conversation-1",
)
# Pass callbacks=[handler] into your chain, agent or RunnableConfig.
handler.flush()

Success for LangChain is a real application invocation that flushes spans. A curl to /api/traces proves the credential only; it does not attach callbacks.

LangGraph

import os
from prismtrace import PRISMtraceLangGraphHandler, wrap_langgraph

handler = PRISMtraceLangGraphHandler(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    host=os.environ["PRISMTRACE_HOST"],
    agent_name="my-graph",
    session_id="graph-run-1",
)
graph = wrap_langgraph(compiled_graph, handler)
graph.invoke({"messages": [("user", "hello")]})
handler.flush()

wrap_langgraph injects callbacks on invoke and stream, so you do not thread config through every call site. Success is one real invoke or stream that flushes spans.

Google ADK

import os
from prismtrace import PRISMtraceADKAdapter
from google.adk.agents import LlmAgent

adapter = PRISMtraceADKAdapter(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
    agent_name="my-adk-agent",
)

agent = LlmAgent(
    model="gemini-2.0-flash",
    instruction="You are a helpful assistant.",
    before_model_callback=adapter.before_model,
    after_model_callback=adapter.after_model,
    before_tool_callback=adapter.before_tool,
    after_tool_callback=adapter.after_tool,
    before_agent_callback=adapter.before_agent,
    after_agent_callback=adapter.after_agent,
)

ADK does not deliver errors through its callbacks. Wrap model and tool calls and forward the exception explicitly, or failed turns are missing from the trajectory:

try:
    ...
except Exception as exc:
    adapter.record_model_error(exc, callback_context=ctx)
    raise

LiteLLM

import os, litellm
from prismtrace import install_litellm

install_litellm(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
)

One call at startup registers a success and failure callback. Do not wrap individual call sites; that defeats the point of LiteLLM.

OpenAI Agents SDK

import os
from agents import Agent, Runner
from prismtrace import install_openai_agents

install_openai_agents(
    api_key=os.environ["PRISMTRACE_API_KEY"],
    project_id=os.environ["PRISMTRACE_PROJECT_ID"],
)

TypeScript and JavaScript

There is no package to install. Instrument the completion handler so each turn POSTs one trace.

const res = await fetch(process.env.PRISMTRACE_HOST + "/api/traces", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-PRISMtrace-Key": process.env.PRISMTRACE_API_KEY,
  },
  body: JSON.stringify({
    project_id: process.env.PRISMTRACE_PROJECT_ID,
    model: "gpt-4o-mini",
    input_messages: [{ role: "user", content: input }],
    output_message: output,
    latency_ms: latencyMs,
    session_id: sessionId,
  }),
});
if (!res.ok) throw new Error("PRISM ingest " + res.status + ": " + (await res.text()));

On serverless, await the call so the function is not frozen mid-POST.

Zero-code proxy

No import and no call-site change. Swap the base URL. Guardrails then run on the call itself: a blocked request never reaches the provider, and a blocked response is withheld while the original is still recorded.

import anthropic, os

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://prism.blockconvey.com/proxy/anthropic",
    default_headers={"X-PRISMtrace-Key": os.environ["PRISMTRACE_API_KEY"]},
)

Three routes exist and only three:

Azure AI Foundry uses the OpenAI route with an x-azure-endpoint header naming your resource.

Step 3: verify

This step is required. Run both checks. Every request sends X-PRISMtrace-Key. If a response says "Missing bearer token" or "Invalid or expired token", you used the wrong header. Add X-PRISMtrace-Key and retry once. Do not invent a JWT.

Check 1: prove the credential

curl -sS -X POST "https://prism.blockconvey.com/api/setup-doctor/handshake" \
  -H "Content-Type: application/json" \
  -H "X-PRISMtrace-Key: $PRISMTRACE_API_KEY" \
  -d '{"project_id": "'"$PRISMTRACE_PROJECT_ID"'", "send_test_trace": true}'

This endpoint always authenticates and its errors are specific. Read detail and act on it rather than retrying.

Check 2: confirm real traffic arrived

curl -sS "https://prism.blockconvey.com/api/setup-doctor?project_id=$PRISMTRACE_PROJECT_ID" \
  -H "X-PRISMtrace-Key: $PRISMTRACE_API_KEY"

In a Python repository you may run python -m prismtrace.verify instead. In a TypeScript repository use curl; do not install Python to verify.

Read live_connected and blocked_step.

Step 4: report

End with these lines and nothing vaguer.

• CREDENTIAL OK or CREDENTIAL FAIL — <reason>
• LIVE CONNECTED — PRISM is receiving live traces from <what you instrumented>.
• or WAITING FOR LIVE — <blocked_step> — <next action>.

Then list files changed, remaining manual steps, and risks.

"I have edited your files" is not an acceptable final answer.

When you cannot run the application

Proving a live trace usually means starting the application, which needs provider keys, a database and a runtime. Sandboxes often have none of these. That is not a failed setup.

If the handshake returned 200, the code is wired and credentials are in the environment and .env.example:

• Stop. Do not loop. Do not ask for OpenAI, Anthropic or database keys purely to verify.
• Report CREDENTIAL OK and WAITING FOR LIVE — instrumented, credential proven — a human must run the application once in their own environment.

That is an acceptable final answer. Handshake-only is never LIVE CONNECTED.

API contract

Base URL https://prism.blockconvey.com. Auth header X-PRISMtrace-Key on every request.

POST /api/traces

session_id, user_identifier, agent_id and agent_name are also read from inside metadata for older callers. Top level wins.

An api_key body field still authenticates and is deprecated; responses using it carry X-PRISMtrace-Deprecation. Use the header.

Returns 200 with the stored trace, including id and cost_usd.

POST /api/spans/ingest

Used by the SDK handlers, not usually by you directly. Body is {trace_id, project_id, spans[], session_id?, metadata?}. Each span carries name, span_type, start_time, and optionally span_id, parent_span_id, input_text, output_text, end_time, duration_ms, status, error_message, token_count_input, token_count_output, cost_usd, model.

Errors

Over a plan volume ceiling the trace is still stored and the response carries X-PRISMtrace-Plan-Warning.

Key scopes

Use an ingest-scoped key in application code. A read-only key returns 403 on ingest by design.

Account limits

Two independent systems. Plan limits are capacity; credits meter AI actions you trigger. Neither hides data already captured.

Free and Builder are the only plans. Guardrails, the Evaluators Hub and the expanded Model Inventory require Builder; everything else works on Free.

Zero credits are charged for anything you do while integrating: trace ingest, span ingest, reading traces, automatic per-trace scoring, trajectory assembly, and guardrail checks are all free. Credits are spent only on actions a human deliberately triggers in the dashboard.

At a zero balance, new AI actions pause. Ingest, reads, automatic scoring, guardrails and alerts all continue. Your integration cannot be blocked by a credit balance.

Failure modes