Sessions API

import { Client } from "@stream-io/stream-agents";

const client = new Client({ apiKey: "your_api_key" });
await client.setUser("jlahey", () =>
  fetch("/api/agent-token").then((response) => response.text()),
);
const agent = client.agent("my-agent");

const session = await agent.sessions.create({ custom: { ticket: "4721" } });

val agents = StreamAgents(apiKey = "your_api_key")
agents.setUser(User(id = "jlahey")) { yourBackend.agentToken() }
val agent = agents.agent("my-agent")

val session = agent.chat()

let agents = StreamAgents(apiKey: "your_api_key")
agents.setUser(User(id: "jlahey")) { try await yourBackend.agentToken() }
let agent = agents.agent("my-agent")

let session = try await agent.sessions.create()
await session.start()

final agents = VisionAgents(
  apiKey: 'your_api_key',
  userId: 'jlahey',
  token: () => http.read(Uri.parse('https://your-app.example.com/api/agent-token')),
);
final agent = agents.agent('my-agent');

final session = await agent.chat();

await session.responses.create("Where is order 1042?");

for await (const event of session.events()) {
  if (event.kind === "response_delta") console.log(event.text);
  if (event.kind === "responded") break;
}

val answer = launch {
    session.events()
        .takeWhile { it.type != "responded" }
        .collect { if (it.type == "response_delta") print(it.text) }
}
session.responses.create("Where is order 1042?")
answer.join()

let events = session.events()
_ = try await session.responses.create("Where is order 1042?")

for await event in events {
    if event.kind == .responseDelta { print(event.text, terminator: "") }
    if event.kind == .responded { break }
}

final events = session.events();
await session.responses.create('Where is order 1042?');

await for (final event in events) {
  if (event.kind == AgentEventKind.responseDelta) stdout.write(event.text);
  if (event.kind == AgentEventKind.responded) break;
}

const session = await agent.sessions.create({
  title: "Order 1042",
  custom: { ticket: "4721" },
});

val session = agent.chat(
    SessionOptions(
        title = "Order 1042",
        custom = buildJsonObject { put("ticket", "4721") },
    ),
)

var options = SessionOptions()
options.title = "Order 1042"
options.custom = ["ticket": "4721"]
let session = try await agent.sessions.create(options)
await session.start()

final session = await agent.chat(const SessionOptions(
  title: 'Order 1042',
  custom: {'ticket': '4721'},
));

const session = await agent.sessions.create({
  id: "order-1042",
  title: "Order 1042",
});

val session = agent.chat(SessionOptions(id = "order-1042", title = "Order 1042"))

var options = SessionOptions()
options.id = "order-1042"
options.title = "Order 1042"
let session = try await agent.sessions.create(options)

const session = await agent.sessions.create({
  modelOverwrites: { llm: "llm-thinking", thinking: "high" },
  tags: { customer_id: "123", plan: "pro" },
  incognito: true,
});

val session = agent.chat(
    SessionOptions(
        modelOverwrites = ModelOverwrites(llm = "llm-thinking", thinking = ModelOverwrites.Thinking.High),
        tags = mapOf("customer_id" to "123", "plan" to "pro"),
        incognito = true,
    ),
)

var options = SessionOptions()
options.modelOverwrites = ModelOverwrites(llm: "llm-thinking", thinking: .high)
options.tags = ["customer_id": "123", "plan": "pro"]
options.incognito = true
let session = try await agent.sessions.create(options)

const updated = await session.update({ title: "Pricing" });

// From your backend, the models too:
// await session.update({ llm: "llm-thinking", thinking: "high" });

val updated = session.update(title = "Pricing")

let updated = try await session.update(title: "Pricing")

final updated = await session.update(title: 'Pricing');

await session.close();
await session.delete();
// A session you only have the id of: agent.sessions.close(id)

session.close()
session.delete()
// A session you only have the id of: sessions.close(id)

await session.close()
try await session.delete()
// A session you only have the id of: agents.close(sessionID:)

await session.close();
await session.delete();
// A session you only have the id of: sessions.stop(id)

// npm install @stream-io/video-client (React: @stream-io/video-react-sdk, see below)
import { VoiceSession } from "@stream-io/stream-agents/video";

await session.voice.start();

// Joins the call "agent:" + session.id from this device, with the microphone on,
// as the user setUser named.
const voice = VoiceSession.of(session);
await voice.join();

// Without a UI framework, play the agent with one <audio> element per remote participant.
// In React, render <ParticipantsAudio /> instead: see Voice UI below.
const call = voice.call;
const playing = new Set<string>();
call?.state.remoteParticipants$.subscribe((participants) => {
  for (const { sessionId } of participants) {
    if (playing.has(sessionId)) continue;
    playing.add(sessionId);
    const audio = document.body.appendChild(document.createElement("audio"));
    call.bindAudioElement(audio, sessionId);
  }
});

// When you are done talking: this device leaves the call, and the conversation
// carries on in writing.
await voice.leave();
await session.voice.stop();

session.startVoice()

// Joins the call "agent:" + session.id with Stream Video, as the user setUser named.
val voice = VoiceSession.attach(context, agents, session.id)
voice.join()

// When you are done talking. Leaving a call you attached to keeps the session.
voice.leave()
session.stopVoice()

try await session.startVoice()

// Joins the call "agent:" + session.id with Stream Video, as the user setUser named.
let voice = try await VoiceSession.attach(agents: agents, sessionID: session.id)
await voice.join()

// When you are done talking. Leaving a call you attached to keeps the session.
await voice.leave()
try await session.stopVoice()

const session = await agent.sessions.get(id);
console.log(session.title, session.state, session.closed_at);
console.log(session.review_score, session.usage?.cost_micros);

val session = agent.sessions.get(id)
println("${session.title} ${session.state} ${session.modality}")
// The review and usage are only given to your backend.

let session = try await agent.sessions.get(id)
print(session.title, session.state, session.modality)
// The review and usage are only given to your backend.

const page = await agent.sessions.query({
  projectId: "support",
  state: "ended",
  createdSince: new Date("2026-10-01T00:00:00Z"),
  createdBefore: new Date("2026-11-01T00:00:00Z"),
  sort: "updated_at",
  limit: 20,
});
const sessions = page.items;

import kotlin.time.Instant

val page = agent.sessions.query(
    SessionQuery(
        projectId = "support",
        state = Session.State.Ended,
        createdSince = Instant.parse("2026-10-01T00:00:00Z"),
        createdBefore = Instant.parse("2026-11-01T00:00:00Z"),
        sort = SessionQuery.Sort.UpdatedAt,
        limit = 20,
    ),
)
val sessions = page.items

var query = SessionQuery(limit: 20)
query.projectID = "support"
query.state = .ended
query.createdSince = try Date("2026-10-01T00:00:00Z", strategy: .iso8601)
query.createdBefore = try Date("2026-11-01T00:00:00Z", strategy: .iso8601)
let page = try await agent.sessions.query(query)
let sessions = page.items

final page = await agent.sessions.query(
  filter: {
    'project_id': 'support',
    'state': 'ended',
    'created_at': {r'$gte': '2026-10-01T00:00:00Z', r'$lt': '2026-11-01T00:00:00Z'},
  },
  sort: const [SessionSort(field: 'updated_at')],
  limit: 20,
);
final sessions = page.items;

const found = await agent.sessions.search("order 1042", {
  state: "ended",
  limit: 5,
});
const one = await agent.sessions.get(found.items[0]!.id);

val found = agent.sessions.search(
    "order 1042",
    SessionQuery(state = Session.State.Ended, limit = 5),
)
val one = agent.sessions.get(found.items.first().id)

var query = SessionQuery(limit: 5)
query.state = .ended
let found = try await agent.sessions.search("order 1042", query)
let one = try await agent.sessions.get(found.items[0].id)

final found = await agent.sessions.query(
  filter: {'text': {r'$q': 'order 1042'}, 'state': 'ended'},
  limit: 5,
);
final one = await agent.sessions.get(found.items.first.id);

const filter = { projectId: "support" };

const page1 = await agent.sessions.query({ ...filter, limit: 50 });

if (page1.has_more && page1.next_cursor) {
  const page2 = await agent.sessions.query({
    ...filter,
    limit: 50,
    cursor: page1.next_cursor,
  });
}

val query = SessionQuery(projectId = "support", limit = 50)

val page1 = agent.sessions.query(query)

val cursor = page1.nextCursor
if (page1.hasMore && cursor != null) {
    val page2 = agent.sessions.query(query.copy(cursor = cursor))
}

var query = SessionQuery(limit: 50)
query.projectID = "support"

let page1 = try await agent.sessions.query(query)

if page1.hasMore, let cursor = page1.nextCursor {
    query.cursor = cursor
    let page2 = try await agent.sessions.query(query)
}

// Fork options take the API's own snake_case names, except modelOverwrites, as on create.
const harder = await session.fork({
  modelOverwrites: { llm: "llm-thinking" },
  title: "Order 1042, thinking harder",
});

const fromThere = await session.fork({ response_id: turns[0]!.id });
const fresh = await session.fork({ messages: false });

val forked = session.fork(
    ForkOptions(
        modelOverwrites = ModelOverwrites(llm = "llm-thinking"),
        title = "Order 1042, thinking harder",
    ),
)
// A fork comes back as a record: attach opens it as a live session, as it does any session by id.
val harder = agents.attach(forked.id)

val fromThere = session.fork(ForkOptions(responseId = turns.first().id))
val fresh = session.fork(ForkOptions(withoutHistory = true))

var options = ForkOptions()
options.modelOverwrites = ModelOverwrites(llm: "llm-thinking")
options.title = "Order 1042, thinking harder"
let forked = try await session.fork(options)
// A fork comes back as a record: attach opens it as a live session, as it does any session by id.
let harder = try await agents.attach(sessionID: forked.id)

let fromThere = try await session.fork(ForkOptions(responseID: turns[0].id))

var fromNothing = ForkOptions()
fromNothing.withoutHistory = true
let fresh = try await session.fork(fromNothing)

final harder = await session.fork(const ForkOptions(
  modelOverwrites: ModelOverwrites(llm: 'llm-thinking'),
  title: 'Order 1042, thinking harder',
));
// A fork is live, but not watched until start().
await harder.start();

final fromThere = await session.fork(ForkOptions(responseId: turns.first.id));
final fresh = await session.fork(const ForkOptions(withoutHistory: true));

await session.responses.rewind(turns[0]!);

session.responses.rewind(turns.first())

try await session.responses.rewind(to: turns[0].id)

await session.responses.rewind(turns.first.id);

// say(text, { interrupt: true }) stops the reply in progress first.
session.say("Hi, I can help with your order.");
await session.responses.create("Where is order 1042?");

for await (const event of session.events()) {
  if (event.kind === "response_delta") console.log(event.text);
  if (event.kind === "responded") break;
}

// interrupt({ requestId }) stops only the reply answering that request, the request_id on its events.
session.interrupt();

val answer = launch {
    session.events()
        .dropWhile { it.type != "responding" }
        .takeWhile { it.type != "responded" }
        .collect { if (it.type == "response_delta") print(it.text) }
}
session.say("Hi, I can help with your order.")
session.responses.create("Where is order 1042?")
answer.join()

session.interrupt()

let events = session.events()
// say(_:interrupt: true) stops the reply in progress first.
try await session.say("Hi, I can help with your order.")
_ = try await session.responses.create("Where is order 1042?")

for await event in events {
    if event.kind == .responseDelta { print(event.text, terminator: "") }
    if event.kind == .responded { break }
}

// interrupt(requestID:) stops only the reply answering that request, the request_id on its events.
try await session.interrupt()

session.say('Hi, I can help with your order.');
final events = session.events();
await session.responses.create('Where is order 1042?');

await for (final event in events) {
  if (event.kind == AgentEventKind.responseDelta) stdout.write(event.text);
  if (event.kind == AgentEventKind.responded) break;
}

session.interrupt();