Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .claude/skills/sdk-swift/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,10 @@ let session = try await agents.agent("myagent").sessions.create()
let turn = try await session.responses.create("Where is order 1042?")
```

`sessions.create` returns once the session's socket is open, so the tools in its options are
answered from the first turn, as in JS. `watch = false` opens it with no socket; `chat` and
`voice` open one whose socket waits for `start()`.

and the advanced form is a request value, not thirty initialiser parameters:

```swift
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -347,7 +347,7 @@ class ChatViewModel(application: Application) : AndroidViewModel(application) {
context = getApplication(),
scope = screenScope,
start = {
sessionId?.let { Assistant.agents.attach(it, tools) } ?: Assistant.agents.agent(Assistant.AGENT_NAME).chat(
sessionId?.let { Assistant.agents.attach(it, tools) } ?: Assistant.agents.agent(Assistant.AGENT_NAME).sessions.create(
SessionOptions(modelOverwrites = ModelOverwrites(llm = Assistant.CHAT_MODEL), tools = tools, returnUrl = Assistant.RETURN_URL),
)
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -237,19 +237,24 @@ final class AgentChat: AIConversationTransport {
if isIncognito {
options.incognito = true
}
session = try await Assistant.agents.chat(options)
session = try await Assistant.agents.sessions.create(options)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}
if !isIncognito {
let channel = try await session.chat()
try await withCheckedThrowingContinuation { (done: CheckedContinuation<Void, any Error>) in
channel.synchronize { error in
if let error { done.resume(throwing: error) } else { done.resume() }
do {
let channel = try await session.chat()
try await withCheckedThrowingContinuation { (done: CheckedContinuation<Void, any Error>) in
channel.synchronize { error in
if let error { done.resume(throwing: error) } else { done.resume() }
}
}
read(channel)
} catch {
// A session opened just now has nobody else to stop it.
if sessionID == nil { await session.close() }
throw error
}
read(channel)
}
follow(session)
await session.start()
self.session = session
publish()
return session
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,6 @@ struct VoiceMode: View {
agents: Assistant.agents, sessionID: session.id)
before = Set(voice.session.turns.map(\.id))
current.session = voice
await voice.session.start()
await voice.join()
} catch is CancellationError {
} catch {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ final class AgentChat {
@ObservationIgnored private let events: EventsController
@ObservationIgnored private var following: Set<AnyCancellable> = []

/// Opens the session's channel and starts following the session.
/// Opens the channel of a session `sessions.create` opened, which is watched already.
static func open(_ session: AgentSession) async throws -> AgentChat {
let channel = try await session.chat()
let chat = AgentChat(session: session, channel: channel)
Expand All @@ -54,7 +54,6 @@ final class AgentChat {
if let error { done.resume(throwing: error) } else { done.resume() }
}
}
await session.start()
chat.hasOlderMessages = !channel.hasLoadedAllPreviousMessages
return chat
}
Expand Down
11 changes: 8 additions & 3 deletions examples/voice_agents/swift_demo/app/SwiftDemo/ChatView.swift
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,16 @@ struct ChatView: View {
do {
// A model that streams its reasoning, which is what fills the reply's thinking
// panel. The call keeps the agent's own model, which answers sooner.
var options = SessionOptions(agent: agent)
var options = SessionOptions()
options.llm = "xai/grok-4.7"
options.tools = Demo.tools
let session = try await Demo.agents.chat(options)
chat = try await AgentChat.open(session)
let session = try await Demo.agents.agent(agent).sessions.create(options)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
do {
chat = try await AgentChat.open(session)
} catch {
await session.close()
throw error
}
} catch is CancellationError {
return
} catch {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ struct VoiceView: View {
.padding(.horizontal)
}
CallControls(voice: voice)
.task { await voice.session.start() }
.padding(.bottom)
} else {
if let failure {
Expand Down
11 changes: 11 additions & 0 deletions sdks/dart/stream_agents/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,18 @@
## Upcoming

🔄 Changed

- `sessions.create` opens the session and follows it, as `chat` and `voice` do: it returns an
`AgentSession` once the socket is open, and answers the device's tools. It returned a `Session`
row before; read that as `session.session`. `chat` and `voice` are now `sessions.create` with
`startVoice` false and true.

✅ Added

- `SessionOptions.watch` - false opens a session with no socket and no tools declared; turns go
through `responses.create`, and `say`, `interrupt`, `events` and `addTools` throw a
`StateError` saying so.

- `StreamAgents.scheduledTasks` - list, change, pause, resume and delete the user's scheduled tasks.
- `session.interrupt(requestId:)` - stops only the reply answering that request.
- `session.say(text, interrupt: true)` - stops what the agent is saying first.
Expand Down
13 changes: 11 additions & 2 deletions sdks/dart/stream_agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,19 @@ final agents = StreamAgents(
### Start a conversation

```dart
final session = await agents.agent('support').chat();
final session = await agents.agent('support').sessions.create();
await session.responses.create('What are your opening hours?');
```

`sessions.create` opens the session and follows it: it returns once the socket is open, so the
device's tools are answered from the first turn. `SessionOptions(startVoice: true)` puts the agent
on the session's call instead of holding it in writing. `chat()` and `voice()` are the same call
with `startVoice` false and true.

`SessionOptions(watch: false)` opens it without a socket, for a caller reading and writing turns
over HTTP alone: no tool is declared, turns go in through `responses.create` and are read back
from `responses.items`, and `say`, `interrupt`, `events` and `addTools` throw a `StateError`.

`session.conversation` is a `LiveValue<Conversation>`: the current transcript and what the
agent is doing, plus a stream of every change. A widget renders it with a `StreamBuilder`:

Expand All @@ -111,7 +120,7 @@ final lookup = AgentTool(
run: (arguments) async => orders.find('${arguments['order_id']}'),
);

final session = await agents.agent('support').chat(SessionOptions(tools: [lookup]));
final session = await agents.agent('support').sessions.create(SessionOptions(tools: [lookup]));
```

The agent only sees what the tool returns.
Expand Down
28 changes: 26 additions & 2 deletions sdks/dart/stream_agents/lib/src/core/agent_session.dart
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ final class AgentSession {
required this._sessions,
List<AgentTool> tools = const [],
this.interim = false,
this._watch = true,
}) : _session = session,
_tools = {for (final tool in tools.reversed) tool.name: tool};

Expand Down Expand Up @@ -105,6 +106,10 @@ final class AgentSession {
final Backend _backend;
final Sessions _sessions;

/// Whether the conversation is followed over a socket. False is `SessionOptions.watch`
/// false: read and written over HTTP, with nothing here to send to.
final bool _watch;

/// The tools whose calls are answered here, by name.
final Map<String, AgentTool> _tools;

Expand Down Expand Up @@ -160,8 +165,12 @@ final class AgentSession {
/// Opens the socket and starts following the conversation. Calling it again, even while it
/// is opening, opens nothing more, and after [close] it opens nothing at all.
///
/// Throws, and reports it on [connection], when the socket cannot be opened.
Future<void> start() => _starting ??= _start();
/// Throws, and reports it on [connection], when the socket cannot be opened, and throws a
/// [StateError] for a session opened with `watch: false`.
Future<void> start() {
_watched();
return _starting ??= _start();
}

Future<void> _start() async {
final Uri uri;
Expand Down Expand Up @@ -207,6 +216,7 @@ final class AgentSession {
/// Each call is a stream of its own, so two listeners each see every event. A listener
/// more than 256 events behind is finished rather than buffered without bound.
Stream<AgentEvent> events() {
_watched();
final subscriber = _Subscriber();
if (_connection.value is Disconnected) {
subscriber.controller.close();
Expand Down Expand Up @@ -300,6 +310,8 @@ final class AgentSession {
/// under each. Only a session this device opened takes tools from it, and a name the agent
/// has of its own, such as a connector's tool, is refused.
Future<void> addTools(List<AgentTool> tools) async {
// A conversation nothing is watching has nowhere to be asked for a call.
_watched();
if (tools.isEmpty) {
return;
}
Expand Down Expand Up @@ -398,6 +410,7 @@ final class AgentSession {
sessions: _sessions,
tools: _tools.values.toList(),
interim: interim,
watch: _watch,
).._unsettled.addAll(_unsettled),
);

Expand Down Expand Up @@ -502,7 +515,18 @@ final class AgentSession {
return () => _conversation.value = _conversation.value.withoutTurn(id);
}

void _watched() {
if (!_watch) {
throw StateError(
'this conversation is not being watched, so there is nothing to send to: open it '
'without watch: false, or use responses.create() and read the turn back through '
'responses.items()',
);
}
}

SessionSocket _held() {
_watched();
final socket = _socket;
if (socket == null) {
throw StateError('start() the session before talking to it');
Expand Down
5 changes: 4 additions & 1 deletion sdks/dart/stream_agents/lib/src/core/convert.dart
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,10 @@ api.CreateSessionRequest createRequestOf(
custom: options.custom,
incognito: options.incognito,
modelOverwrites: overwritesOf(options.modelOverwrites),
tools: options.tools.isEmpty ? null : [for (final tool in options.tools) sessionToolOf(tool)],
// Unwatched, nothing here answers a call, so no tool is declared.
tools: !options.watch || options.tools.isEmpty
? null
: [for (final tool in options.tools) sessionToolOf(tool)],
tags: options.tags.isEmpty ? null : options.tags,
returnUrl: _set(options.returnUrl),
// The router remembers only for a user id, and a device only ever means its own user.
Expand Down
9 changes: 9 additions & 0 deletions sdks/dart/stream_agents/lib/src/core/models.dart
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,7 @@ final class SessionOptions {
this.returnUrl,
this.memory,
this.timezone,
this.watch = true,
});

/// An id to hold the session by, for a caller that wants to know it before the session
Expand Down Expand Up @@ -476,6 +477,14 @@ final class SessionOptions {
/// and it is remembered as the user's for the scheduled tasks that follow. Null sends none,
/// and a zone the router does not know is refused.
final String? timezone;

/// Whether to follow the conversation over its socket, which is what answers [tools] and
/// reports what the agent is doing word by word.
///
/// False opens it without a socket: [tools] are not declared, nothing here answers a call,
/// and `say`, `interrupt`, `decide`, `events` and `addTools` throw a [StateError]. Turns go
/// in through `responses.create` and are read back from `responses.items`.
final bool watch;
}

/// What a session remembers about the user [Backend.userId] names. It is always theirs: a
Expand Down
71 changes: 55 additions & 16 deletions sdks/dart/stream_agents/lib/src/core/sessions.dart
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
import 'dart:math';

import 'agent_session.dart';
import 'backend.dart';
import 'convert.dart';
import 'errors.dart';
import 'generated/api.dart' as api;
import 'models.dart';
import 'tools.dart';
Expand All @@ -10,26 +13,29 @@ const _itemPage = 200;

/// Conversations: the ones being held and the ones that were.
///
/// What comes back are rows rather than live handles, because reading a conversation back is
/// not holding one and most of these are over. `StreamAgents.attach` follows one that is
/// still running.
/// [create] opens one and follows it. What is read back are rows rather than live handles,
/// because reading a conversation back is not holding one and most of these are over.
/// `StreamAgents.attach` follows one that is still running.
final class Sessions {
Sessions(this._operations, {this.agent, this._userId = ''});
Sessions(this._operations, this._backend, {this.agent});

final api.Operations _operations;

/// Who is asking, which is whose memories a session reads.
final String _userId;
/// Where sessions opened here are followed, and who is asking, which is whose memories a
/// session reads.
final Backend _backend;

/// The agent name every call here is about, or null for all of this caller's.
final String? agent;

/// Opens a conversation without following it, for a caller building its own state layer.
/// Opens a conversation and follows it, answering [SessionOptions.tools] on this device.
///
/// Held in writing unless [SessionOptions.startVoice] is set. It returns once the backend is
/// holding the conversation, so a session that comes back is one already listening.
Future<Session> create([SessionOptions options = const SessionOptions()]) =>
_create(options, options.startVoice);
/// holding the conversation and the socket is open, so a session that comes back is one
/// already listening. With [SessionOptions.watch] false no socket is opened and no tool
/// declared; its turns go through [AgentSession.responses].
Future<AgentSession> create([SessionOptions options = const SessionOptions()]) =>
_open(options, voice: options.startVoice);

/// A page of this caller's conversations, the ones that ended included.
///
Expand Down Expand Up @@ -155,9 +161,38 @@ final class Sessions {
/// A conversation's turns, whether or not this process is holding it.
Responses responses(String id) => Responses._(_operations, id);

Future<Session> _create(SessionOptions options, bool startVoice) async {
final request = createRequestOf(options, startVoice: startVoice, agent: agent, userId: _userId);
return sessionOf(await _operations.createSession(body: request));
Future<AgentSession> _open(SessionOptions options, {required bool voice}) async {
// Taken before the request, so what is declared is what is answered here.
final tools = options.watch ? List.of(options.tools) : const <AgentTool>[];
final request = createRequestOf(
options,
startVoice: voice,
agent: agent,
userId: _backend.userId,
);
final session = AgentSession(
sessionOf(await _operations.createSession(body: request)),
backend: _backend,
sessions: this,
tools: tools,
watch: options.watch,
);
if (!options.watch) {
return session;
}
try {
await session.start();
} on AgentsException {
// The agent is in the conversation whether or not anybody here can follow it, so it is
// stopped rather than left holding a call nobody is listening to.
try {
await stop(session.id);
} on AgentsException {
// Reporting why the socket did not open matters more than this.
}
rethrow;
}
return session;
}

Future<ListPage<Session>> _query(
Expand Down Expand Up @@ -368,9 +403,13 @@ final class Responses {
}
}

/// Opens a conversation on its call or in writing, whatever [options] say.
Future<Session> openSession(Sessions sessions, SessionOptions options, {required bool voice}) =>
sessions._create(options, voice);
/// Opens a conversation on its call or in writing, whatever [options] say, as
/// [Sessions.create] does.
Future<AgentSession> openSession(
Sessions sessions,
SessionOptions options, {
required bool voice,
}) => sessions._open(options, voice: voice);

/// Gives a running session more of its caller's tools, declared as when it opened.
Future<void> addSessionTools(Sessions sessions, String id, List<AgentTool> tools) =>
Expand Down
Loading
Loading