Keep five objects separate in your integration. A session authorizes public runtime calls, and a conversation groups messages. A stream reports what happens during a turn. A file is an input identified by a public reference; an artifact is a durable output. Each has its own lifetime and affects the UI differently.
This integration overview shows session and error boundaries; the documented lifecycle below adds conversations, files, and outputs.
Choose the right object for each job
Scroll horizontally to see all columns.
| Object | Role in the integration | Decision it does not make |
|---|---|---|
| Session | Holds public session metadata and the token used for runtime calls. | Which conversation a user is viewing. |
| Conversation | Groups messages under a conversationRef. | Whether a new turn has completed. |
| Stream | Yields events such as message deltas, completion, interactions, and errors. | Whether the app may ignore a pending approval or interruption. |
| File | A previously uploaded input referenced by fileRef. | Whether the agent can read it under its current policy. |
| Artifact | A durable output that can be fetched by artifactRef. | How the app should render every possible output. |
Trace a document review
Suppose an operations portal receives inspection-notes.pdf and asks an agent to summarize the reported condition. First read the public filePolicy. Check its upload flag, allowed MIME types, and maximum upload size before sending content. The documented upload body uses base64; there is no separate multipart or signed-URL upload flow. A new file can be processing before it becomes available, so do not treat those states as equivalent.
After upload, pass the returned fileRef in streamMessage({ fileRefs }) for the turn. The SDK docs do not describe a separate typed turn-attachment object beyond these public refs. During the stream, append each message:delta to the visible draft instead of replacing earlier text. Treat message:complete as the event that carries the finished content and related public outputs. An artifact:created event may arrive before completion; the completed event can also include artifacts.
Completed document review (fictional portal)
Input:inspection-notes.pdffinished upload with statusavailable; its publicfileRefis attached to the turn.
Conversation: The turn is associated with the currentconversationRef.
Stream result:message:completereturns a summary and an artifact reference for a review table.
UI state: The summary is marked complete; the table is opened withgetArtifact()and a fallback renderer is ready ifrenderHintsare absent.
This sample assumes the agent is allowed to read the uploaded file and is configured to produce that artifact. Check the policy before showing file or artifact controls. Context-library file operations are a separate case: they require both a materialized workspace binding and policy support.
Render only what the events confirm
When token-level rendering is unnecessary, collectAssistantMessage() can consume the stream and return the assembled message with any usage, references, files, or artifacts produced. renderHints on an artifact are advisory presentation metadata, not a rendering contract; keep a safe fallback. Check artifact capability before fetching, and handle an out-of-bound ref as unavailable rather than probing another session or workspace.
For conversations, cancellation, interactions, and event types, read conversations and streaming. Continue with files and artifacts, sessions and storage, and workspaces and external agents.