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

Next chapter:

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