Concepts

Everything in Assistant Cloud hangs off a project. A project has two hosts, a plan and a set of settings; inside it, workspaces own threads, threads hold messages, and every assistant response that is reported or traced leaves a run with its spans, a few events and, when someone rates it, a score. This page names those objects once, so the other pages can use the words without explaining them again.

The project and its two hosts

A project is created in the dashboard and identified by an id such as proj_0ltyjcuaxpv1. It answers on two hosts:

The project id's underscore becomes a hyphen in the frontend host name. A credential is accepted only on its own host: a key presented to the frontend host, or a token presented to the backend host, is refused with 403 Origin does not match project ID. The assistant-cloud package talks to both hosts, and the assistant-ui runtimes drive it.

Users and workspaces

Every request acts as one user inside one workspace, and a workspace owns its threads. How the two are named depends on the credential:

An id is 1 to 255 characters with no whitespace or control characters. The user is who a conversation belongs to and who counts as an active user for the plan; the workspace is who may list and open the thread. A server that names the same workspace for several users gives them a shared thread list, which is how a team inbox or an organisation's shared history is built. Users and workspaces has the strategies and the erasure route.

Threads and messages

A thread is one conversation: a title, last_message_at, an archived flag, an external_id you may set, up to 16 short metadata strings, and counters the cloud keeps (its run count and whether a user ever copied, stopped, regenerated or edited in it). Threads are listed per workspace, newest activity first.

A message is a node in the thread's tree. parent_id names the message it follows, so an edit or a regeneration starts a new branch under the same parent, and the cloud computes each message's height from its parent. format names the shape of content: aui/v0 is what the local runtime stores, ai-sdk/v6 what the AI SDK runtime stores, and a read may ask for a conversion between them. Stored through the REST API, a message may also carry an external_id of yours, which makes storing it idempotent; the client methods do not send one. Threads and Messages go through both objects field by field.

Runs and spans

A run is one assistant response: its status (completed, incomplete or error) and outcome, the model and provider that served it, tokens and cost, duration and time to first token, the steps it took and the tools it called, and a trace_id. The SDK reports a run when the response finishes, and a server can report the same run from the inside by exporting its OpenTelemetry spans to the project; a report and an export that carry the same trace id merge into one run.

A span is one step of a run: a model generation, a tool call, or a sampling call a tool made on its own. Spans come from server traces, or are derived from the SDK's report. Runs the cloud makes for itself, such as writing a thread title, are stored with the source system and never appear in your figures.

Events and scores

An event is something the user did: a kind such as message_sent or run_stopped, the ids involved, a small integer, and a few short properties. Events never carry message text. The runtimes record sixteen kinds from their store, and the Engagement page and the satisfaction reading are built from them.

A score is a named value on a run, a thread or a message: numeric, categorical or boolean, with a source that says who wrote it (end_user, api, human or evaluator). The thumbs in the message components are a boolean score named feedback; evaluators are model judges that write scores on a sample of new conversations.

Ids, time and limits

Ids are a prefix and 24 characters: thread_0…, msg_0…, run_0…, usr_anon_0…, score_…. Timestamps are ISO 8601 in UTC; the dashboard renders them in your own zone and counts days, months and plan periods in UTC. Every size and count limit is on Limits, and the plan's active user and title allowances on Plans and pricing.

One turn, on the wire

What the AI SDK runtime sends for the first turn of a new conversation, in order:

The local runtime follows the same sequence with aui/v0 messages. LangGraph, LangChain and ADK skip the two message requests and the run report, because their backend keeps the transcript. A server with an API key makes the same calls itself, minus the token routes. Which runtime lists what each integration stores and reports.