Concepts Overview

How the Bigdata.com Research Agent and Workflows behave at the protocol level, and the order to read these guides.

The Research Agent and Workflows share the same response model: a streaming sequence of typed events delivered over Server-Sent Events. The guides in this section cover the cross-cutting protocol-level behavior that both services exhibit — streaming, grounding, charts, errors, and conversation continuity.

If you have not built against the Research Agent or Workflows before, work through these pages in order. They are self-contained, but each builds on the previous one’s vocabulary.

Recommended reading order

1. Streaming responses

   Start here. Defines the SSE format, every public message type, the typical order of events in a request, and a canonical Python handler the rest of the docs build on. Read it

2. Grounding and citations

   How GROUNDING references attribute spans of the answer to their source documents, the critical buffering rule for offset math, and a worked example that turns a streamed response into a Markdown answer with inline citations. Read it

3. Code execution and charts

   How the agent runs Python to compute and plot from the data it retrieved, what a CHART event contains, and how to render one. Read it

4. Error handling

   The difference between HTTP-level errors and in-stream errors, what each of ERROR, TOOL_ERROR, and LLM_RETRY means, and a retry/backoff pattern for 429 and 5xx responses. Read it

5. Conversation continuity

   Resuming Research Agent conversations with chat_id and checkpoints, the persistence_mode switch, the "INITIAL" reset sentinel, and resuming Workflows by execution_id. Read it

What each page covers

Page	You will learn
Streaming responses	Every public message type (purpose, key fields, when each is emitted) and a complete Python handler that dispatches on type.
Grounding and citations	The structure of a GroundingReference, the cumulative-answer buffering rule, AUDIT linkage, and how to render Markdown footnote-style citations.
Code execution and charts	When the agent writes and runs Python, what a CHART event carries, and how to render it.
Error handling	HTTP error codes, in-stream ERROR vs. TOOL_ERROR vs. LLM_RETRY, an error-aware handler, and a retry/backoff helper.
Conversation continuity	chat_id, execution_id, from_checkpoint_id, checkpoint_id, persistence_mode, the "INITIAL" sentinel, and multi-turn / branching examples.

Next steps

Once you are comfortable with the concepts, move on to the service-specific quickstarts and how-to guides.

Research Agent quickstart

Send your first Research Agent request end-to-end.

Workflows quickstart

Define and execute your first workflow, inline or by template id.

Non-streaming pattern

Consume the stream end-to-end and print the complete answer in one go.

Workflow templates

Anatomy of a workflow template, input placeholders, content filters, and research plans.

Running a workflow

Submit a run that outlives your connection, then read, watch, or cancel it.