Sessions API

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

const client = new Client({ apiKey: "your_api_key" });
await client.setUser("jlahey", async () => {
  // Your server mints it: https://getstream.io/agents/docs/auth/#generating-a-token
  const response = await fetch("/api/agent-token");
  if (!response.ok) throw new Error(`token: ${response.status}`);
  return 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)
await session.start()

final session = await agent.chat(const SessionOptions(id: 'order-1042', title: 'Order 1042'));

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)
await session.start()

final session = await agent.chat(const SessionOptions(
  modelOverwrites: ModelOverwrites(llm: 'llm-thinking', thinking: Thinking.high),
  tags: {'customer_id': '123', 'plan': 'pro'},
  incognito: true,
));

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)

const session = await agent.sessions.resume(sessionId);
// A page's own tools come back with it: agent.sessions.resume(sessionId, { tools })
await session.responses.create("Where were we?");

val session = agents.attach(sessionId)
session.responses.create("Where were we?")

let session = try await agents.attach(sessionID: sessionId)
_ = try await session.responses.create("Where were we?")

final session = await agents.attach(sessionId);
await session.responses.create('Where were we?');

// 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()

await session.startVoice();

// Joins the call "agent:" + session.id with Stream Video, as the user VisionAgents was given.
final voice = await VoiceSession.attach(agents, session.id);
await voice.join();

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

const session = await agent.sessions.get(id);
console.log(session.title, session.state, session.closed_at);
// On your server, an ended session carries its review and usage.
console.log(session.review_score, session.usage?.cost_micros);

session = await agent.sessions.get(session_id)
print(session.state, session.modality, session.closed_at)
if session.usage:
    print(session.usage.input_tokens, session.usage.output_tokens, session.usage.cost_micros)

session = agent.sessions.get(id)
p session.values_at("state", "modality", "closed_at")
usage = session["usage"]
p usage.values_at("input_tokens", "output_tokens", "cost_micros") if usage

$session = $agent->sessions->get($id)->created;
var_dump($session->state, $session->modality, $session->closedAt);
if ($session->usage !== null) {
    echo $session->usage->inputTokens, ' ', $session->usage->outputTokens, ' ', $session->usage->costMicros, PHP_EOL;
}

session, err := agent.Sessions.Get(ctx, id)
if err != nil {
	log.Fatal(err)
}
fmt.Println(session.State, session.Modality, session.ClosedAt)
if session.Usage != nil {
	fmt.Println(session.Usage.InputTokens, session.Usage.OutputTokens, session.Usage.CostMicros)
}

var session = (await agent.Sessions.GetAsync(id)).Created;
Console.WriteLine($"{session.State} {session.Modality} {session.ClosedAt}");
if (session.Usage is { } usage)
{
    Console.WriteLine($"{usage.InputTokens} {usage.OutputTokens} {usage.CostMicros}");
}

let session = agent.sessions.get(id).await?;
println!("{} {} {:?}", session.state, session.modality, session.closed_at);
if let Some(usage) = &session.usage {
    println!("{} {} {}", usage.input_tokens, usage.output_tokens, usage.cost_micros);
}

const session = await agent.sessions.get(id);
console.log(session.title, session.state, session.closed_at);
// The review and usage are only given to your server.

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.

final session = await agent.sessions.get(id);
print('${session.title} ${session.state.name} ${session.modality.name}');
// The review and usage are only given to your backend.

const page = await agent.sessions.query({
  filter: { project_id: "support" },
  limit: 20,
});
const sessions = page.items;

val page = agent.sessions.query(
    filter = SessionFilter.ProjectId("support"),
    limit = 20,
)
val sessions = page.items

let page = try await agent.sessions.query(filter: .projectID("support"), limit: 20)
let sessions = page.items

final page = await agent.sessions.query(
  filter: {'project_id': 'support'},
  limit: 20,
);
final sessions = page.items;

const page = await agent.sessions.query({
  filter: { $or: [{ project_id: "support" }, { project_id: "billing" }] },
  sort: [{ field: "pinned" }, { field: "last_message_at" }],
});

for (const session of page.items) {
  console.log(session.pinned_at ? "pinned" : "", session.title);
}

val page = agent.sessions.query(
    filter = SessionFilter.Or(
        SessionFilter.ProjectId("support"),
        SessionFilter.ProjectId("billing"),
    ),
    sort = listOf(
        SessionSort(SessionSortField.Pinned),
        SessionSort(SessionSortField.LastMessageAt),
    ),
)

for (session in page.items) {
    println("${if (session.pinnedAt != null) "pinned" else ""} ${session.title}")
}

let page = try await agent.sessions.query(
    filter: .or([.projectID("support"), .projectID("billing")]),
    sort: [.pinned, .lastMessageAt()]
)

for session in page.items {
    print(session.pinnedAt != nil ? "pinned" : "", session.title)
}

final page = await agent.sessions.query(
  filter: {
    r'$or': [
      {'project_id': 'support'},
      {'project_id': 'billing'},
    ],
  },
  sort: const [
    SessionSort(field: 'pinned'),
    SessionSort(field: 'last_message_at'),
  ],
);

for (final session in page.items) {
  print('${session.pinnedAt != null ? 'pinned' : ''} ${session.title}');
}

const page = await agent.sessions.query({
  filter: { review_score: { $lte: 2 } },
  sort: [{ field: "review_score", direction: 1 }],
  limit: 50,
});

for (const row of page.items) {
  const session = await agent.sessions.get(row.id);
  console.log(session.review_score, session.review_notes);
}

page = await agent.sessions.query(
    filter={"review_score": {"$lte": 2}},
    sort=[{"field": "review_score", "direction": 1}],
    limit=50,
)

for row in page.items:
    session = await agent.sessions.get(row.id)
    print(session.review_score, session.review_notes)

page = agent.sessions.query(
  filter: { review_score: { "$lte" => 2 } },
  sort: [{ field: "review_score", direction: 1 }],
  limit: 50
)

page["items"].each do |row|
  session = agent.sessions.get(row["id"])
  p session.values_at("review_score", "review_notes")
end

$page = $agent->sessions->query(
    filter: ['review_score' => ['$lte' => 2]],
    sort: [['field' => 'review_score', 'direction' => 1]],
    limit: 50,
);

foreach ($page->items as $row) {
    $session = $agent->sessions->get($row->id)->created;
    echo $session->reviewScore, ' ', $session->reviewNotes, PHP_EOL;
}

page, err := agent.Sessions.Query(ctx, client.Query{
	Filter: client.Filter{"review_score": client.Filter{"$lte": 2}},
	Sort:   []client.Sort{{Field: client.SortReviewScore, Direction: 1}},
	Limit:  50,
})
if err != nil {
	log.Fatal(err)
}

for _, row := range page.Items {
	session, err := agent.Sessions.Get(ctx, row.Id)
	if err != nil {
		log.Fatal(err)
	}
	if session.ReviewScore != nil && session.ReviewNotes != nil {
		fmt.Println(*session.ReviewScore, *session.ReviewNotes)
	}
}

var page = await agent.Sessions.QueryAsync(new SessionQuery
{
    Filter = new()
    {
        ["review_score"] = new Dictionary<string, object?> { ["$lte"] = 2 },
    },
    Sort = [new SessionSort("review_score", 1)],
    Limit = 50,
});

foreach (var row in page.Items)
{
    var session = (await agent.Sessions.GetAsync(row.Id)).Created;
    Console.WriteLine($"{session.ReviewScore} {session.ReviewNotes}");
}

use serde_json::json;
use vision_agents::{types, Query};

let page = agent
    .sessions
    .query(Query {
        filter: json!({"review_score": {"$lte": 2}}),
        sort: vec![types::SessionSort {
            field: types::SessionSortField::ReviewScore,
            direction: types::SessionSortDirection::try_from(1).ok(),
        }],
        limit: Some(50),
        ..Default::default()
    })
    .await?;

for row in &page.items {
    let session = agent.sessions.get(&row.id).await?;
    println!("{:?} {:?}", session.review_score, session.review_notes);
}

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

val found = agent.sessions.search(
    "order 1042",
    filter = SessionFilter.ProjectId("support"),
    limit = 5,
)
val one = agent.sessions.get(found.items.first().id)

let found = try await agent.sessions.search(
    "order 1042",
    filter: .projectID("support"),
    limit: 5
)
let one = try await agent.sessions.get(found.items[0].id)

final found = await agent.sessions.search(
  'order 1042',
  filter: {'project_id': 'support'},
  limit: 5,
);
final one = await agent.sessions.get(found.items.first.id);

const pinned = await session.pin();
console.log(pinned.pinned_at);

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

val pinned = session.pin()
println(pinned.pinnedAt)

session.unpin()
// A session you only have the id of: agent.sessions.pin(id)

let pinned = try await session.pin()
print(pinned.pinnedAt as Any)

try await session.unpin()
// A session you only have the id of: agent.sessions.pin(id)

final pinned = await session.pin();
print(pinned.pinnedAt);

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

let page = await agent.sessions.query({ limit: 200 });

while (true) {
  for (const session of page.items) {
    await analyze(session);
  }
  if (!page.has_more || !page.next_cursor) break;
  page = await agent.sessions.query({ limit: 200, cursor: page.next_cursor });
}

cursor = ""

while True:
    page = await agent.sessions.query(limit=200, cursor=cursor)
    for session in page.items:
        await analyze(session)
    if not page.has_more:
        break
    cursor = page.next_cursor

cursor = nil

loop do
  page = agent.sessions.query(limit: 200, cursor: cursor)
  page["items"].each { |session| analyze(session) }
  break unless page["has_more"]

  cursor = page["next_cursor"]
end

$cursor = null;

do {
    $page = $agent->sessions->query(limit: 200, cursor: $cursor);
    foreach ($page->items as $session) {
        analyze($session);
    }
    $cursor = $page->hasMore ? $page->nextCursor : null;
} while ($cursor !== null);

query := client.Query{Limit: 200}

for {
	page, err := agent.Sessions.Query(ctx, query)
	if err != nil {
		log.Fatal(err)
	}
	for _, session := range page.Items {
		analyze(session)
	}
	if !page.HasMore || page.NextCursor == nil {
		break
	}
	query.Cursor = *page.NextCursor
}

string? cursor = null;

do
{
    var page = await agent.Sessions.QueryAsync(new SessionQuery { Limit = 200, Cursor = cursor });
    foreach (var session in page.Items)
    {
        await AnalyzeAsync(session);
    }
    cursor = page.HasMore ? page.NextCursor : null;
} while (cursor is not null);

use vision_agents::Query;

let mut cursor = None;

loop {
    let page = agent
        .sessions
        .query(Query { limit: Some(200), cursor, ..Default::default() })
        .await?;
    for session in &page.items {
        analyze(session).await?;
    }
    if !page.has_more {
        break;
    }
    cursor = page.next_cursor;
}

// 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 { items: turns } = await session.responses.list();
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));

// 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();