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
| Event | Fields | Meaning |
|---|---|---|
start | conversation id, session id | The turn began. |
thinking | content | Progress while the model works. |
tool | name, status (started or completed) | A tool the model is using. |
final | conversation id, query id, answer | The complete answer. |
error | code, message | The service reports a failure inside the stream. |
done | none | The 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.