Paragon Agent

The in-product AI assistant. Investigate traces, propose judges, debug behaviors — in the dashboard or in Slack.

The Paragon Agent is the AI assistant built into Polarity. It has read access to your traces, judges, behaviors, and datasets, and answers questions like:

"What looks suspicious in this trace?"
"Why is my helpful-refund behavior firing low this week?"
"Help me improve this judge prompt — sample some traces, then suggest a rewrite."
"What changed in the last 24 hours?"

It runs in the dashboard at /judgement-agent and as the @Polarity bot in Slack.

Two response modes

Mode	What it does	When to use
`normal`	One tool call (search, lookup, fetch), then synthesize an answer	Quick lookups, trace explanations, single-question debug
`deep`	Up to three tool round-trips before answering	Root-cause investigations, multi-trace patterns, behavior debugging

Set in the chat input dropdown, or via mode: "deep" on the API call.

Tools

The agent has access to thirteen structured tools — enough to investigate, propose, and author end-to-end:

Tool	What it does
`search_traces(filters, sort, order, limit)`	Filter trace events by event_type, tool_name, status, model, sandbox/experiment, duration, cost, or full-text on input/output. Returns ranked rows.
`get_trace(id \| root_span_id)`	Pull the full conversation by trace id (any span_id in it) or root_span_id. Returns ordered spans plus any failing behavior verdicts.
`get_span(span_id)`	Inspect a single span — input, output, tool_call args, duration, parent context.
`search_similar_traces(query \| reference_trace_id, limit)`	Find traces that look semantically similar to a query string or an existing reference trace (substring across input/output/tool_name).
`list_judges(query, limit)`	List judges in the workspace, optionally filtered by name/description substring.
`get_judge(id_or_name)`	Look up a judge's full config — prompt, categories, version, alignment.
`create_judge(name, type, prompt, ...)`	Author a new judge (binary / classification / score). Persists immediately.
`list_behaviors(query, limit)`	List behaviors in the workspace, optionally filtered by name substring.
`get_behavior(id_or_name)`	Pull a behavior's config with its linked judge inlined.
`behavior_stats(id_or_name)`	Runtime stats for one behavior: detection rate, total matched traces, 28-day activity, per-option breakdown, sample of recent matched traces.
`aggregate_behavior_impact(behavior_id, window_days)`	Total runs, fail count, fail rate over the window, and delta vs the prior equal-length window.
`create_behavior(judge_id, name, flavor, ...)`	Wrap an existing judge in a behavior so it fires on live traces.
`query_supabase(table, filters, sort, limit)`	Read-only PostgREST query against allowlisted data tables (traces, judges, behaviors, experiments, datasets, score rules, alert rules, etc.). Owner-scoped automatically.

The model picks tools autonomously based on your question. You don't compose them — you ask a question, the agent calls whatever it needs.

Workflows you can ask for

Trace investigation

"What looks suspicious in trace abc123 and why?"

The agent fetches the trace, walks the spans, and replies with a text summary plus a table listing the suspicious spans. Span IDs are rendered as [trace:abc] chips that link directly into the trace tree.

Behavior debugging

"Why is Helpful Refund Response firing false on so many traces today?"

Samples recent firings, looks for common patterns in the agent's responses, suggests rubric tweaks. In deep mode it'll also score a sample against a candidate revised prompt and report the delta.

Judge improvement

"Help me improve the prompt for the Sentiment judge. Score a sample, then suggest a rewrite."

Pulls the current prompt, samples N traces, runs them through the judge, identifies disagreements, and proposes a new prompt with side-by-side scores. Apply or discard.

Trace search

"Show me the 10 most expensive traces from yesterday where error_rate > 0 and the agent called the refund_full tool."

Builds a structured filter, queries, returns a ranked table.

Broad triage

"What changed this week?"

Fans out across traces, behavior firings, and recent automations to surface what stands out.

Block types the agent emits

The agent responds with a stream of typed blocks rather than free-form text. Each block renders distinctly:

Block	Renders as
`text`	Primary copy
`thought`	Collapsible reasoning summary
`table`	Sortable results table (used for trace lists)
`chart`	Inline chart — 9 types supported (line, bar, stacked, pie, scatter, etc.) for behavior-firing trends, cost over time, latency distribution
`span_card`	A trace span rendered as a card with attrs, latency, cost, and a deep-link into the trace timeline

Inline references inside text and table-row detail fields use chip syntax — [trace:abc], [behavior:xyz], [judge:foo] — which the UI auto-renders as clickable pills.

Threads

Every conversation is a thread. The dashboard URL carries ?thread=<id> so you can share a link or bookmark a debug session. The Slack bot maps one Slack thread to one Paragon thread, so follow-up @Polarity mentions in the same thread carry context.

Endpoint	Purpose
`POST /v1/paragon/chat`	Start or continue a thread (SSE stream)
`GET /v1/paragon/threads`	List recent threads
`GET /v1/paragon/threads/{id}`	Fetch full transcript
`DELETE /v1/paragon/threads/{id}`	Remove a thread

Calling the agent from code

The chat endpoint streams Server-Sent Events. Most users won't touch it directly — the dashboard and Slack are the primary surfaces — but it's exposed for custom integrations.

from polarity import Polarity
 
plr = Polarity()
 
for event in plr.paragon.chat(message="why is helpful-refund firing false today?",
                              mode="deep"):
    if event.type == "block":
        print(event.block.kind, event.block.body)
    elif event.type == "done":
        break

Personas

The agent runs in one of four personas, selectable via agent_kind:

Persona	Tuned for
`global_copilot` (default)	General Q&A across all data
`agent_search`	Locating relevant traces fast
`rubric_builder`	Drafting and refining judge prompts
`custom_agent`	A workspace-defined persona (configured by admins)

The dashboard's /judgement-agent page uses global_copilot; rubric_builder is invoked automatically when you ask to improve a judge from the judge detail page.

What the agent can and can NOT do


Can	Read traces, spans, judges, behaviors. Propose new judges + behaviors as reviewable drafts. Run a judge against a trace. Render charts and span cards inline.
Cannot (yet)	Write to your DB. Delete existing judges/behaviors. Re-run agent code in a sandbox (coming soon — will use sandboxes to verify candidate fixes).

Authoring tools produce reviewable drafts — judges and behaviors created via create_judge / create_behavior show up in the dashboard with an Accept / Reject banner. Nothing persists until you click Accept.

Next steps

Slack integration — talk to the same agent via @Polarity in any Slack channel
Judges — what the agent samples and improves
Behaviors — what the agent debugs and tunes

Alerts Slack