02. Basic Run, Stream, and Session

This chapter explains the three most important usage patterns:

1. one-shot calls with run(...)
2. streaming calls with stream(...)
3. multi-turn conversations with sessions

1. createAgentSdk()

The clean SDK entry point is:

import { createAgentSdk } from 'actoviq-agent-sdk';

const sdk = await createAgentSdk();

You can pass options such as:

• workDir
• tools
• mcpServers
• agents
• skills
• permissionMode
• permissions

2. One-shot calls with run(...)

Use run(...) when the task does not need a persistent conversation.

const result = await sdk.run('Summarize what this SDK is for.');
console.log(result.text);
console.log(result.toolCalls);

3. Streaming calls with stream(...)

Use stream(...) when you want tokens as they arrive.

const stream = sdk.stream('Explain sessions in one paragraph.');

for await (const event of stream) {
  if (event.type === 'response.text.delta') {
    process.stdout.write(event.delta);
  }
}

const result = await stream.result;
console.log('\nfinal:', result.text);

4. Multi-turn sessions

Create a session when context should survive across turns.

const session = await sdk.createSession({ title: 'Demo Session' });

await session.send('Remember that the release codename is Sparrow.');
const reply = await session.send('What is the release codename?');

console.log(session.id);
console.log(reply.text);

5. Where to find the session ID

You can inspect the session ID in several places:

1. session.id
2. result.sessionId
3. sdk.sessions.list()

Example:

const session = await sdk.createSession({ title: 'My Session' });
console.log(session.id);

const sessions = await sdk.sessions.list();
console.log(sessions);

6. Where history is stored

The clean SDK session store is local and file-based.

Default location:

~/.actoviq/actoviq-agent-sdk

Each session is persisted there through the session store. Stored data includes:

• session ID
• title
• tags
• metadata
• messages
• run history
• timestamps

7. Can the storage location be changed?

Yes. Pass sessionDirectory when creating the SDK:

const sdk = await createAgentSdk({
  sessionDirectory: 'E:/my-session-store',
});

That changes where clean SDK session files are written.

8. Can the session ID be customized?

Not currently.

The session ID is generated by the SDK. What you can customize instead:

• title
• tags
• metadata
• sessionDirectory

9. How to list and resume history

const sessions = await sdk.sessions.list();
console.log(sessions);

const previous = await sdk.resumeSession('your-session-id');
const reply = await previous.send('Continue from the previous context.');
console.log(reply.text);

10. Session management example

const sdk = await createAgentSdk();

const session = await sdk.createSession({
  title: 'Release Planning',
  tags: ['release', 'ci'],
  metadata: { owner: 'team-a' },
});

await session.send('Remember that release steps must include npm pack --dry-run.');

console.log('current id:', session.id);
console.log('stored sessions:', await sdk.sessions.list());

const restored = await sdk.resumeSession(session.id);
console.log((await restored.send('What must the release include?')).text);

11. Running tasks in parallel

Use sdk.parallel() to run independent tasks concurrently:

const results = await sdk.parallel([
  () => sdk.run('Summarize the project.'),
  () => sdk.run('List action items.'),
], { maxConcurrency: 2 });

Use sdk.race() to return the first completed result:

const fastest = await sdk.race([
  () => sdk.run('Quick answer', { model: 'claude-haiku-4-5' }),
  () => sdk.run('Detailed answer', { model: 'claude-sonnet-4-6' }),
]);

12. Session lifecycle

Configure sessionManager to auto-manage idle timeouts and session limits:

const sdk = await createAgentSdk({
  sessionManager: { idleTimeoutMs: 30 * 60_000, maxSessions: 100 },
});

// Check stats or prune old sessions
const stats = await sdk.sessions.stats();
await sdk.sessions.prune({ status: 'idle', olderThan: '1h' });

13. Session checkpoints

Save and restore session state for experimentation:

const cp = await session.saveCheckpoint('before-refactor');
await session.send('Risky refactoring...');
await session.restoreCheckpoint(cp.id); // undo

Full details for all orchestration features are in chapter 07.

Next chapter:

• 03-tools-permissions-skills-mcp.md