Agent SDK · Running agents

Text helpers.

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

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.