Agent SDK · Running agents

Text helpers.

Filter a run's stream to assistant text, plus the module-level run and stream helpers.

These helpers filter the event stream to just text — useful when you only need the response text and don't care about tool calls, usage, or status events.

`runner.streamText(agent, input, options?)`

Returns an async generator that yields raw string deltas. Throws SafetyReplaceError when the server replaces the output (safety filter). Throws Error on stream errors.

TypeScript

try {
  for await (const chunk of runner.streamText(
    { name: 'poet', instructions: 'Write a haiku.' },
    'Write about the ocean.',
  )) {
    process.stdout.write(chunk);
  }
} catch (err) {
  if (err instanceof SafetyReplaceError) {
    console.error(`\nSafety replace: ${err.categories.join(', ')}`);
  } else {
    console.error(err);
  }
}

Note

Why throw on safety replace? The original text has already been yielded to the consumer by the time the replace event arrives. Throwing forces the consumer to handle the replacement explicitly — silently dropping it would lose the replacement message.

`runner.runText(agent, input, options?)`

Non-streaming convenience that returns just the final output text. Safety replace is handled by throwing SafetyReplaceError. Throws if the stream produced any error events.

TypeScript

const text = await runner.runText(
  { name: 'helper' },
  'What is 2 + 2?',
);
console.log(text); // "4"

`SafetyReplaceError`

TypeScript

class SafetyReplaceError extends Error {
  readonly categories: string[];
  // message = replacement content (or empty string)
}

Convenience functions

The SDK exports default-runner-backed convenience functions so you don't need to instantiate a Runner for simple use cases:

TypeScript

import { run, stream, streamText, runText } from '@maincode-ai/matilda-agent-sdk';

// These are equivalent to defaultRunner.run(), defaultRunner.stream(), etc.
const result = await run(agent, input, options);
const text = await runText(agent, input, options);

for await (const event of stream(agent, input, options)) { /* ... */ }
for await (const chunk of streamText(agent, input, options)) { /* ... */ }

These use the default MatildaCore singleton (configured via configureClient()). For isolated config or auth, instantiate your own Runner.