# Text helpers

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

Source: https://maincode.com/docs/python-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.stream_text(agent, prompt, **options)`

An async generator that yields raw string deltas. Raises `SafetyReplaceError` when the server replaces the output (safety filter). Raises `MatildaStreamError` on stream errors.

```python
from matilda_agent_sdk import Runner, SafetyReplaceError

runner = Runner()


async def main():
    try:
        async for chunk in runner.stream_text(
            {"name": "poet", "instructions": "Write a haiku."},
            "Write about the ocean.",
        ):
            print(chunk, end="", flush=True)
    except SafetyReplaceError as err:
        print(f"\nSafety replace: {', '.join(err.categories)}")
```

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

## `runner.run_text(agent, prompt, **options)`

Non-streaming convenience that returns just the final output text. Raises `SafetyReplaceError` on safety replacement, and propagates `MatildaAgentStreamError` if the stream produced error events.

```python
text = await runner.run_text(
    {"name": "helper"},
    "What is 2 + 2?",
)
print(text)  # "4"
```

## `SafetyReplaceError`

```python
class SafetyReplaceError(MatildaError):
    categories: list[str]
    # str(err) = replacement content (or empty string)
```

## Convenience functions

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

```python
from matilda_agent_sdk import run, run_text, stream, stream_text

# These are equivalent to default_runner.run(), default_runner.stream(), etc.
result = await run(agent, prompt, ...)        # AgentRunResult
text = await run_text(agent, prompt, ...)     # str

async for event in stream(agent, prompt, ...):
    ...                                       # AgentEvent

async for chunk in stream_text(agent, prompt, ...):
    ...                                       # str
```

These use the shared default client (installed via `configure_default_client()`, or created with defaults on first use). For isolated config or auth, instantiate your own `Runner`.