Safeguard Docs
Safeguard AI SDKs

Streaming

Read a Safeguard AI answer as events with the TypeScript, Python and Go SDKs.

Streaming

stream sends the prompt and returns the answer as events while Safeguard AI works. The request is sent when you first read from the stream.

Events

EventFieldsMeaning
startconversation id, session idThe turn began.
thinkingcontentProgress while the model works.
toolname, status (started or completed)A tool the model is using.
finalconversation id, query id, answerThe complete answer.
errorcode, messageThe service reports a failure inside the stream.
donenoneThe stream is over.

An event type that an SDK version does not know arrives as an unknown event (with the raw data) and is never dropped or thrown, so a newer API does not break an older SDK. Ignore what you do not need.

TypeScript

import { Safeguard, isEvent } from "@safeguard-sh/sdk";

const client = new Safeguard();

const stream = client.stream("In two sentences, what is a software bill of materials?");
for await (const ev of stream) {
  if (isEvent(ev, "start")) console.error(`conversation ${ev.conversationId}`);
  else if (isEvent(ev, "thinking")) process.stderr.write(".");
  else if (isEvent(ev, "tool")) console.error(`\ntool ${ev.name} ${ev.status}`);
  else if (isEvent(ev, "final")) console.log(`\n${ev.answer}`);
  else if (isEvent(ev, "error")) console.error(`error ${ev.code}: ${ev.message}`);
}

Or skip the events: const answer = await client.stream("...").finalAnswer();. Break out of the loop to close the connection. A stream can be iterated once.

Python

from safeguard_sdk import Error, Final, Safeguard, Start, Thinking, Tool

client = Safeguard()

with client.stream("In two sentences, what is a software bill of materials?") as events:
    for event in events:
        if isinstance(event, Start):
            print("conversation", event.conversation_id)
        elif isinstance(event, Thinking):
            print(".", end="", flush=True)
        elif isinstance(event, Tool):
            print("\ntool", event.name, event.status)
        elif isinstance(event, Final):
            print("\n" + event.answer)
        elif isinstance(event, Error):
            print("error", event.code, event.message)

Use the stream as a context manager so the connection closes. events.final_answer() waits and returns the result. The async client has the same surface, shown in Examples.

Go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	safeguard "safeguard.sh/sdk"
)

func main() {
	client, err := safeguard.NewClient()
	if err != nil {
		log.Fatal(err)
	}
	s, err := client.Stream(context.Background(), "In two sentences, what is a software bill of materials?", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer s.Close()

	for s.Next() {
		switch ev := s.Event().(type) {
		case safeguard.StartEvent:
			fmt.Fprintln(os.Stderr, "conversation", ev.ConversationID)
		case safeguard.ThinkingEvent:
			fmt.Fprint(os.Stderr, ".")
		case safeguard.ToolEvent:
			fmt.Fprintln(os.Stderr, "\ntool", ev.Name, ev.Status)
		case safeguard.FinalEvent:
			fmt.Println("\n" + ev.Answer)
		case safeguard.ErrorEvent:
			fmt.Fprintln(os.Stderr, "error", ev.Code, ev.Message)
		}
	}
	if err := s.Err(); err != nil {
		log.Fatal(err)
	}
}

s.FinalAnswer() reads the rest of the stream and returns the answer. An error event ends the stream and s.Err() returns it as an *APIError. A stream that ends before the final answer reports io.ErrUnexpectedEOF. Cancelling the context or calling s.Close() stops it.

Example output (shortened):

conversation f1d41b23-...
.
A software bill of materials (SBOM) is a formal, machine-readable inventory of ...

A stream that errors partway is not retried by the SDK. Start a new query if you want another try.

On this page