SuperBryn Pipecat Observer
One call in your Pipecat bot reports every call to SuperBryn.
attach(task, runner_args) sends your agent's own record of each call: the transcript, tool calls, each reply's
latency parts, the models and settings that ran, token, audio and character usage, every LLM request and what became
of it, and every STT, LLM, TTS or transport failure. SuperBryn does every calculation on its side. It works on any
transport Pipecat speaks (Daily, Twilio, Plivo, Vobiz, Exotel, WebRTC, WebSocket) with no carrier credentials.
- SuperBryn test calls are reported for testing (surface
testing): the agent's record sits next to the test. - Every other call is a production call (surface
observability): it is recorded in stereo and appears in Monitor.production=Falseturns production reporting off.
Each call is reported once, as call.started when the pipeline starts and call.ended when it finishes. Everything
runs in the background: it adds no latency and never raises into your pipeline.
Install
pip install -U "superbryn-pipecat-observer>=0.12.0"
Setup
export SUPERBRYN_API_KEY=sbryn_... # one key with test_data:write and obs:write
export SUPERBRYN_AGENT_ID=3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b # the agent's SuperBryn ID (not needed with an agent key)
Add one call to your bot, once per call, after building the PipelineTask and before it runs:
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from superbryn_pipecat_observer import attach
async def bot(runner_args):
...
task = PipelineTask(pipeline, params=PipelineParams())
report = attach(task, runner_args)
await PipelineRunner().run(task)
That's all: attach adds its own observer, its own on_pipeline_finished hook and, for production calls, the
recorder. Pass runner_args (what Pipecat's runner hands your bot) so test calls are recognised and the call is
named as before; a bot with no runner arguments passes what it knows as keywords instead (below).
Options
| Option | Environment variable | What it does |
|---|---|---|
api_key |
SUPERBRYN_API_KEY |
A SuperBryn API key: test calls need test_data:write and prompt versions obs:write; production calls take any valid key (the setup screens' keys hold both). Without one nothing is sent. |
agent_id |
SUPERBRYN_AGENT_ID |
The agent's SuperBryn ID, a UUID. Test calls need it unless the key is the agent's own key. Any other value is left out, with one warning. |
production |
True by default. False reports SuperBryn test calls only: production calls send nothing and are not recorded. |
|
record |
True by default. False reports production calls without SuperBryn's recording (for example for compliance). |
|
simulation |
False by default. True marks production calls as your own UAT / simulation runs (observability.mode: "track"): SuperBryn keeps their transcript without analysis or billing, and they are not recorded and name no prompt. |
|
capture_logs |
True by default: a production call carries the INFO+ log lines its own code wrote (loguru, and logging at the levels your config lets through), up to 1000, each cut to 2,000 characters. Other calls in the same process are left out (call attach() in the task that runs the pipeline), and your logging config is not changed. False sends none. |
|
custom_data |
Your own keys for this call, a dict sent as given (see below). | |
prompt, prompt_version |
The prompt template your agent runs, and your label for this version (see Prompt sync). | |
base_url |
SUPERBRYN_BASE_URL |
The SuperBryn API origin, https://api.superbryn.com by default. |
superbryn_call_id, from_number, to_number, call_id, call_data |
What your bot already knows about the call, when runner_args doesn't carry it: SuperBryn's test ID, the caller and the dialled number, your own ID for the call, and a parsed telephony handshake (parse_telephony_websocket). |
|
SUPERBRYN_OBSERVER_ENABLED |
false, 0, no or off turns attach off for the whole process, as in 0.11. |
SUPERBRYN_TEST_API_KEY, SUPERBRYN_WEBHOOK_URL, WEBHOOK_URL, AGENT_ID and VERSION_ID, which 0.11 read, are
not read any more.
The handle
attach returns the call's handle. Use it for anything known only during the call, until the call ends:
report.set_custom_data({"ticket_id": "TKT-9001"}) # replaces custom_data
report.update_custom_data({"appointment_booked": True}) # merges into it; other keys are kept
report.set_call_end_reason("transfer_to_human") # sent as ended_reason instead of the end frame's
report.set_recording_url("https://my-bucket/.../call.mp3") # production calls: your own recording (see below)
Custom data
custom_data is sent at the top of call.ended exactly as you give it: the same key names and the same value types
(a value JSON can't hold, such as a datetime, is sent as its text). SuperBryn's pre-ingestion filters and profiles
match these key names, so keys like workflow_id or tenant_id route production calls to the right source and
profile. Set it in attach(custom_data=...) for what you know at the start, and with set_custom_data() or
update_custom_data() for what you learn during the call.
Prompt sync
Pass the prompt template your agent runs (placeholders unfilled) so SuperBryn knows exactly which prompt each call ran on:
report = attach(task, runner_args, prompt=PROMPT_TEMPLATE, prompt_version="v13")
Each call carries context.prompt_ref = {"hash": "sha256:...", "version": "v13"}, and the template's text is pushed
to SuperBryn once per host per version (POST /public-api/v1/prompts, which needs obs:write), with the tools in
the pipeline's LLM context. A prompt change you deploy shows up in the agent's settings in SuperBryn. Every call also
sends the system message of its LLM context as context.system_prompt, which SuperBryn matches as text when no
prompt= is given. Any stack can compute the hash: sha256 over the template's UTF-8 bytes, written sha256:<hex>
(superbryn_pipecat_observer.prompt_ref(template, version)).
How a SuperBryn test call is recognised
In this order:
superbryn_call_id=is passed;runner_args.bodyhassuperbryn_call_id(webhook, Custom cURL and Pipecat Cloud starts);- a Daily dial-in SIP header ends in
x-superbryn-call-id; - a telephony WebSocket carries a
superbryn_call_idcustom parameter (Twilio stream parameters, Exotel custom parameters), read fromcall_data=, elserunner_args.call_data, else the handshake your bot parsed itself withparse_telephony_websocket; - otherwise, the caller or the dialled number is one of SuperBryn's test numbers (fetched with your key, any valid
SuperBryn API key, and cached for an hour in a temp file every process on the host shares; a refused key is
asked again after an hour, an unanswered fetch after a minute). A test call's data is stored only with
test_data:write: with a Monitor-only key, SuperBryn's test calls are recognised and kept out of Monitor.
A value that still holds a template placeholder such as {From} is ignored, with a warning. A call SuperBryn says is
not one of its tests is not reported again as a production call.
A test call's call_id is the telephony call's own ID (call_data.call_id, the Daily dial-in call_id), which
SuperBryn's Custom cURL trigger matches; a production call's is runner_args.session_id, the ID 0.11 gave Monitor
calls. call_id= names both.
Production calls
Recording. Unless record=False, a production call is recorded in stereo, the caller on the left channel and the
agent on the right: attach puts Pipecat's AudioBufferProcessor right before your output transport. When the call
ends, the WAV goes straight to SuperBryn's storage through a short-lived presigned URL fetched with your key, and the
temp file is deleted. No S3 settings are needed. A recording that can't be made or uploaded leaves the call
unrecorded, never unreported. A call recognised as a SuperBryn test is never recorded. attach must run before the
task does: once the pipeline runs, no recorder can be added (one warning).
Your own recording. Pass its URL (public or pre-signed) with report.set_recording_url(url); set before the
task runs, SuperBryn's recording is not started. It is sent with recording_url_source: "external".
observability also carries mode (observe, or track with simulation=True) and, on Daily dial-in and dial-out
calls, direction.
What a report contains
POST {base_url}/public-api/v1/calls/agent-data, with the key in X-API-Key. Every event repeats the call's identity:
schema_version, event_id (pc:<call_id>:started or :ended, the same on a retry), event, surface,
source: "pipecat", call_id, agent_id, from, to, and started_at, when the pipeline started. Every
start_ms, end_ms and at_ms counts from started_at. call.ended adds:
| Field | What it holds |
|---|---|
ended_at, ended_reason, ended_by |
When the pipeline finished; why (ended, cancelled, stopped, error, or yours); and who ended it when that is known: agent (a processor such as an end-call tool asked the pipeline to end), caller (the transport's client disconnected first) or system (a fatal error). |
transcript[] |
Each line: id, role, text, start_ms, end_ms; caller lines confidence; agent lines interrupted. Agent text is what the output transport played. |
tool_calls[] |
id, name, arguments, result, is_error, start_ms, end_ms, and turn_id, the agent line it fed; <tool_use>{...}</tool_use> blocks an LLM was prompted to write are lifted out of the text as tool calls. |
diagnostics |
pipeline; configuration (STT, LLM and TTS with the voice, turn detection, interruptions, tools); turn_latencies[] per reply (transcriber_ms, endpointing_ms, model_ms, voice_ms, turn_ms); usage; llm_requests[] with each one's outcome; errors[]; dtmf[]; and, on production calls, logs[] (ts, level, name, message). |
context |
system_prompt, prompt_ref, room_url (the Daily room), and environment (this package's, Pipecat's and Python's versions, the transport, and 0.11's pipeline_version tag). |
custom_data |
Your keys, as given. |
testing |
Test calls: superbryn_call_id, when the call carried one. |
observability |
Production calls: mode and direction, and recording_url, stereo_recording_url, recording_url_source on call.ended. |
No audio is sent in the body, and the package computes no averages: SuperBryn works them out from these records.
Latency and usage need Pipecat's metrics: attach switches on enable_metrics and enable_usage_metrics when your
PipelineParams leave them unset, and logs one warning when you turned one off.
Agent Config Sync (opt-in)
Push your agent's configuration to SuperBryn as a reviewable draft. Requires an agent-scoped API key; nothing syncs unless you call it explicitly:
from superbryn_pipecat_observer import sync_config
sync_config(
pipeline,
api_key="sk_agent_...", # or SUPERBRYN_API_KEY
identity={"name": "Support Agent", "type": "inbound", "agent_modality": "voice"},
behavior={"prompt": open("prompt.txt").read()},
policy_guardrails=open("guardrails.md").read(),
)
The helper walks the pipeline's processors — recursing into nested pipelines, ParallelPipeline branches, and ServiceSwitcher / LLMSwitcher members, and unwrapping custom wrapper classes — to fill the llm / stt / tts / voice blocks automatically. For switchers, the primary (initially active) service fills the block and the next member is reported in its fallback sub-block. It also reads the LLM context to fill behavior.prompt (the system message) and tools (the advertised function schemas) — explicit behavior= / tools= overrides always win. Extraction reads a fixed allow-list of configuration attributes (including private fields like _settings, _model, _voice_id where Pipecat services store their settings); credential attributes such as provider API keys are never part of that list and are never read or transmitted. The manifest lands as a pending draft in the SuperBryn dashboard for review; it never changes the live agent directly. Use async_sync_config(...) inside a running event loop, or build_manifest_from_pipeline(...) + sync_manifest(...) to inspect/modify the manifest before pushing. The API origin is base_url=, else SUPERBRYN_BASE_URL, else SUPERBRYN_API_BASE_URL, else https://api.superbryn.com.
Override sections accept exactly the fields of the canonical manifest schema (unknown keys raise ValueError locally — the endpoint rejects them anyway):
| Keyword | Fields |
|---|---|
identity |
name, type (inbound/outbound), agent_modality (voice/chat), description, pain_point, gender, age, dob |
behavior |
prompt, flow |
tools |
list of {name, description, schema, server: {type, url}} |
language |
primary_language, additional_languages: [{code, priority}] |
telephony |
phone_number, ivr_config: {enabled, number} |
Plus top-level strings/ints: policy_guardrails, additional_details, concurrency_calls. Sections the pipeline can't expose (identity, telephony, guardrails, ...) are supplied through these explicit overrides.
Docs: https://docs.superbryn.com/advanced/agent-sync
Logs
Log lines (logger superbryn_pipecat_observer.call_report) start with SUPERBRYN_CALL_REPORT_: SENT when SuperBryn
accepted an event (with any optional field it dropped), DISABLED without an API key or with
SUPERBRYN_OBSERVER_ENABLED off, WARNING for an agent ID that isn't a UUID or caller numbers the key can't read,
RETRY, REJECTED (with what to change) and FAILED for delivery problems, and ERROR for anything else. None of
them affects the call. When the pipeline finishes, the work before the recording's upload (call.started, the end
frame, finishing the file and getting its upload URL) gets at most 12 seconds, and call.ended after it 12 more; the upload itself can take up to 2 minutes for a long call, after the caller has gone.
Upgrading from 0.11
0.12.0 replaces both 0.11 entry points (SuperbrynObserver with monitor_and_create_task /
simulate_and_create_task for production calls, and attach_test_data for SuperBryn test calls) with attach. It
posts a new body to a new endpoint, so pin the new version and change the setup in the same deploy.
Before (0.11):
from pipecat.pipeline.runner import PipelineRunner
from superbryn_pipecat_observer import SuperbrynObserver, attach_test_data
async def bot(runner_args):
...
observer = SuperbrynObserver(
agent_id="support-bot",
agent_name="Support Bot",
custom_metadata={"workflow_id": "wf_inbound", "tenant_id": 42},
prompt=PROMPT, prompt_version="v13",
)
task = observer.monitor_and_create_task(
pipeline, context, runner_args=runner_args, transport=transport, idle_timeout_secs=120
)
attach_test_data(task, runner_args)
...
observer.set_custom_metadata({"booked": True})
await PipelineRunner().run(task)
After (0.12):
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from superbryn_pipecat_observer import attach
async def bot(runner_args):
...
task = PipelineTask(pipeline, params=PipelineParams(), idle_timeout_secs=120)
report = attach(
task, runner_args,
custom_data={"workflow_id": "wf_inbound", "tenant_id": 42,
"agent_id": "support-bot", "agent_name": "Support Bot"},
prompt=PROMPT, prompt_version="v13",
)
...
report.update_custom_data({"booked": True})
await PipelineRunner().run(task)
Environment: SUPERBRYN_API_KEY is one key with both test_data:write and obs:write (it replaces
SUPERBRYN_TEST_API_KEY); SUPERBRYN_AGENT_ID is the agent's SuperBryn ID, a UUID (a free-form AGENT_ID is not
read; drop it when you use the agent's own key); SUPERBRYN_BASE_URL is the API origin (it replaces
SUPERBRYN_WEBHOOK_URL and WEBHOOK_URL; config sync still falls back to SUPERBRYN_API_BASE_URL).
What else changed:
- You build the
PipelineTaskyourself (with thePipelineTaskkeywords you passed tomonitor_and_create_task), then callattach; it adds the recorder before the output transport, asmonitor_*did. Remove aSuperbrynAudioRecorderyou placed in the pipeline yourself, and the observer fromobservers=[...].simulate_and_create_taskisattach(..., simulation=True). Recording is always stereo. custom_metadata,extra_metadataandset_custom_metadata()arecustom_dataandupdate_custom_data(), sent in the body'scustom_data(0.11 sent them incall.metadata).agent_name, and anagent_idthat is not a SuperBryn UUID, are not options any more: keep them incustom_dataunder the same names if your filters use them.session_id=iscall_id=;recording_url=/stereo_recording_url=arereport.set_recording_url(url);capture_logsandprompt/prompt_versionare unchanged.transport,audio_recorder,extended_capture,max_log_records,first_message,sync_prompt,enabled,num_channelsanddefer_upload(withstart_audio_upload()andabort()) are gone.- The package no longer sends averages or counts (
latency.avg_ms/p95_ms,speech_stats, turn-detection, interruption, VAD, connection and pipeline summaries,duration_seconds); SuperBryn computes them from the raw records. Turn latency keys are snake_case (transcriber_ms,endpointing_ms,model_ms,voice_ms,turn_ms). ended_reasonisended/cancelled/stopped/error(0.11's production calls saidcompleted/cancelled).
A prompt for your coding agent (copy and paste):
Upgrade this Pipecat bot from superbryn-pipecat-observer 0.11 to 0.12.0 (pip: "superbryn-pipecat-observer>=0.12.0").
1. Pin superbryn-pipecat-observer>=0.12.0 in the project's dependencies.
2. Remove every use of the old API and its imports: SuperbrynObserver(...), SuperbrynAudioRecorder(...) (and its
recorder.processor inside the Pipeline([...])), observer.monitor_and_create_task(...),
observer.simulate_and_create_task(...), observer.monitor_pipeline(...), observer.simulate_pipeline(...), the
deprecated observe_* / track_* methods, observer.register_task_handlers(...), observer.attach_to_task(...), the
observer inside PipelineTask(observers=[...]), and attach_test_data(task, ...).
3. Where monitor_and_create_task / simulate_and_create_task built the task, build it yourself:
task = PipelineTask(pipeline, params=<the params= passed before, else PipelineParams()>, <every other keyword
passed before>). Then add one call right after it and BEFORE the task runs:
report = attach(task, runner_args, ...) (from superbryn_pipecat_observer import attach)
Pass runner_args when the bot has them (whatever was passed as runner_args= before). If attach_test_data was
given superbryn_call_id=, from_number=, to_number=, call_id= or call_data=, pass them to attach the same way.
4. Map the old options onto attach:
- custom_metadata= and extra_metadata= -> custom_data= (one dict). Keep every key name and every value type
exactly as it is: SuperBryn's filters and profiles match on them (for example workflow_id).
- agent_name= -> add "agent_name": <same value> to custom_data. agent_id= -> if it is the agent's SuperBryn ID
(a UUID), pass agent_id= (or set SUPERBRYN_AGENT_ID); otherwise add "agent_id": <same value> to custom_data.
- session_id= -> call_id=. prompt= / prompt_version= / capture_logs= -> the same names.
- simulate_and_create_task / simulate_pipeline -> attach(..., simulation=True).
- recording_url= / stereo_recording_url= -> report.set_recording_url(url), called right after attach.
- api_key= -> api_key=. webhook_url= / api_base_url= -> base_url= with the URL's origin only
(https://host, no path).
- Drop transport=, audio_recorder=, extended_capture=, max_log_records=, first_message=, sync_prompt=,
num_channels=. If sync_prompt=False was set, do not pass prompt=. If enabled=False was set, do not call
attach in that case.
5. Replace observer.set_custom_metadata(...) with report.update_custom_data(...) (same argument), and
observer.get_custom_metadata() with the bot's own copy of the dict. If the observer is passed to other functions
or tools, pass `report` instead.
6. If the bot uses defer_upload=True, observer.start_audio_upload() or observer.abort(), STOP and ask me: 0.12 has no
consent gate; the closest is attach(..., record=False).
7. Environment and deployment config: put SuperBryn's Agent data key (it holds both
test_data:write and obs:write) in SUPERBRYN_API_KEY and remove SUPERBRYN_TEST_API_KEY; replace a free-form AGENT_ID with SUPERBRYN_AGENT_ID set to the agent's SuperBryn
agent ID (a UUID), or remove it when the key is the agent's own key; replace SUPERBRYN_WEBHOOK_URL / WEBHOOK_URL /
SUPERBRYN_API_BASE_URL with SUPERBRYN_BASE_URL set to the API origin (https://api.superbryn.com unless told
otherwise); remove VERSION_ID if only this package used it. Keep SUPERBRYN_OBSERVER_ENABLED as it is.
8. Do not change anything else in the bot. Show the diff when done.
Links
License
MIT, see LICENSE.
Made by SuperBryn. Support: support@superbryn.com
Metadata
Release files for superbryn-pipecat-observer 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| superbryn_pipecat_observer-0.12.0.tar.gz | 104.2 kB | Without provenance | Details for superbryn_pipecat_observer-0.12.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| superbryn_pipecat_observer-0.12.0-py3-none-any.whl | Python 3 | none | any | Details for superbryn_pipecat_observer-0.12.0-py3-none-any.whl |
Total release size: 163.5 kB
Release files / superbryn_pipecat_observer-0.12.0.tar.gz
| Download URL | superbryn_pipecat_observer-0.12.0.tar.gz |
|---|---|
| Size | 104.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
75bc19484c587057f7a73fd3ee957b171c192bca61529d7fc2911df0b1f8a19c
|
|
BLAKE2b-256 checksum How to use checksums |
e240b455447401de965ad4ac5d45d3da51bcf497781b639699e0d90ede7a19ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / superbryn_pipecat_observer-0.12.0-py3-none-any.whl
| Download URL | superbryn_pipecat_observer-0.12.0-py3-none-any.whl |
|---|---|
| Size | 59.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a8082e76926a1776303b2626b58e7f14a03d14d0d583abbcebfdfbf7778e8e38
|
|
BLAKE2b-256 checksum How to use checksums |
5cdc943b25f4dde5770b9148598f67bfd99753c80a89f04f9599258ae85a3de9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for superbryn-pipecat-observer 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.