# Text helpers

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

Source: https://maincode.com/docs/agent-sdk-text-helpers
Section: Agent SDK · Matilda documentation

---

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.

```ts
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.

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

## `SafetyReplaceError`

```ts
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:

```ts
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`.