Streaming agent completions

This is a beta feature according to Algolia’s Terms of Service (“Beta Services”).

The Agent Studio API client can stream agent completions as server-sent events (SSE). Instead of waiting for the full response, you iterate over events as the agent generates them, which is useful for chat interfaces and other interactive experiences. Each client exposes a streaming variant of createAgentCompletion that returns a stream you iterate over.

Supported languages

Streaming is available in these API clients:

Go API client version 4.45.0 and later
JavaScript API client version 5.54.0 and later
Python API client version 4.42.0 and later

For a client without streaming support, createAgentCompletion returns the complete response in a single call. You can also stream from the HTTP endpoint with the stream parameter.

Stream completions

Open a stream and iterate over each event as it arrives. The following example streams a completion from a simple message:

// Initialize the client
client, err := agentStudio.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
if err != nil {
  // The client can fail to initialize if you pass an invalid parameter.
  panic(err)
}

// Use the streaming variant to iterate over events
stream, err := client.CreateAgentCompletionStream(client.NewApiCreateAgentCompletionRequest(
  "76710f1b-8231-42e5-b0d1-f43aac618e15", agentStudio.CompatibilityMode("ai-sdk-5"),
  agentStudio.NewEmptyAgentCompletionRequest().SetMessages(agentStudio.ArrayOfMessageV4AsMessagesUnion(
    []agentStudio.MessageV4{*agentStudio.UserMessageV4AsMessageV4(
      agentStudio.NewEmptyUserMessageV4().SetRole("user").SetContent("Hello, how are you?"))}))))
if err != nil {
  // handle the eventual error
  panic(err)
}

defer func() { _ = stream.Close() }()

for stream.Next() {
  event := stream.Current()
  if event.Err != nil {
    // handle the eventual per-event deserialization error
    continue
  }

  fmt.Println(*event.Data)
}

err = stream.Err()
if err != nil {
  // handle the eventual error
  panic(err)
}

// Initialize the client
const client = agentStudioClient('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

// Use the streaming variant to iterate over events
for await (const event of client.createAgentCompletionStream({
  agentId: '76710f1b-8231-42e5-b0d1-f43aac618e15',
  compatibilityMode: 'ai-sdk-5',
  agentCompletionRequest: { messages: [{ role: 'user', content: 'Hello, how are you?' }] },
})) {
  console.log(event.data);
}

# Initialize the client
# In an asynchronous context, you can use AgentStudioClient instead, which exposes the exact same methods.
client = AgentStudioClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# Use the streaming variant to iterate over events
for event in client.create_agent_completion_stream(
    agent_id="76710f1b-8231-42e5-b0d1-f43aac618e15",
    compatibility_mode="ai-sdk-5",
    agent_completion_request={
        "messages": [
            {
                "role": "user",
                "content": "Hello, how are you?",
            },
        ],
    },
):
    print(event.data)

For the full set of examples and every language, see Create a completion.

Raw and typed streams

Each client offers two streaming methods for the completion endpoint. Use the typed method for application code and the raw method when you need the events without parsing. Typed: CreateAgentCompletionStream (Go), createAgentCompletionStream (JavaScript), create_agent_completion_stream (Python). The client parses each event’s JSON payload for you:

In Go, the returned stream’s Current() method returns a StreamEvent: read the parsed payload from event.Data, the original event from event.Raw, and a parsing error, if any, from event.Err.
In JavaScript and Python, iteration yields StreamEvent objects: read the parsed payload from event.data, the original event from event.raw, and a parsing error, if any, from event.error.

Raw: CreateAgentCompletionStreamRaw (Go), createAgentCompletionStreamRaw (JavaScript), create_agent_completion_stream_raw (Python). The client exposes the underlying SSE events without parsing them. Use this to proxy the stream to another service, parse events yourself, or forward event types the typed payload doesn’t model:

In Go, the method returns an sse.Decoder. Each event carries the JSON payload in its Data field, and you close the decoder yourself.
In JavaScript and Python, iteration yields ServerSentEvent objects whose data field holds the JSON-encoded payload as a string.

The following example reads the raw events from the same completion:

// Initialize the client
client, err := agentStudio.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")
if err != nil {
  // The client can fail to initialize if you pass an invalid parameter.
  panic(err)
}

// Use the raw streaming variant to access the unparsed server-sent events
decoder, err := client.CreateAgentCompletionStreamRaw(client.NewApiCreateAgentCompletionRequest(
  "76710f1b-8231-42e5-b0d1-f43aac618e15", agentStudio.CompatibilityMode("ai-sdk-5"),
  agentStudio.NewEmptyAgentCompletionRequest().SetMessages(agentStudio.ArrayOfMessageV4AsMessagesUnion(
    []agentStudio.MessageV4{*agentStudio.UserMessageV4AsMessageV4(
      agentStudio.NewEmptyUserMessageV4().SetRole("user").SetContent("Hello, how are you?"))}))))
if err != nil {
  // handle the eventual error
  panic(err)
}

defer func() { _ = decoder.Close() }()

for decoder.Next() {
  fmt.Println(string(decoder.Event().Data))
}

err = decoder.Err()
if err != nil {
  // handle the eventual error
  panic(err)
}

// Initialize the client
const client = agentStudioClient('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY');

// Use the raw streaming variant to access the unparsed server-sent events
for await (const event of client.createAgentCompletionStreamRaw({
  agentId: '76710f1b-8231-42e5-b0d1-f43aac618e15',
  compatibilityMode: 'ai-sdk-5',
  agentCompletionRequest: { messages: [{ role: 'user', content: 'Hello, how are you?' }] },
})) {
  console.log(event.data);
}

# Initialize the client
# In an asynchronous context, you can use AgentStudioClient instead, which exposes the exact same methods.
client = AgentStudioClientSync("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY")

# Use the raw streaming variant to access the unparsed server-sent events
for event in client.create_agent_completion_stream_raw(
    agent_id="76710f1b-8231-42e5-b0d1-f43aac618e15",
    compatibility_mode="ai-sdk-5",
    agent_completion_request={
        "messages": [
            {
                "role": "user",
                "content": "Hello, how are you?",
            },
        ],
    },
):
    print(event.data)

Handle disconnections

Streaming requests connect to the first host only. They don’t retry or fail over to another host, and this behavior is the same in every client.

If the connection drops mid-stream, re-initiate the stream from your application.

An SSE stream can’t resume mid-delivery, so an automatic retry could replay events you already received or skip events you didn’t. Only your application knows how much of the response it processed, so it decides how to resume the conversation.

Reference

Streaming agent completions

Supported languages

Stream completions

Raw and typed streams

Handle disconnections

See also

​Supported languages

​Stream completions

​Raw and typed streams

​Handle disconnections

​See also

Supported languages

Stream completions

Raw and typed streams

Handle disconnections

See also