generate_text

API reference for non-streaming text generation

generate_text() runs the model/tool loop and returns a completed GenerateTextResult.

Use it for one-off, non-streaming model calls where you do not need agent state.

Import

from ai_query import generate_text

Signature

async def generate_text(
    *,
    model: LanguageModel,
    prompt: str | None = None,
    system: str | None = None,
    messages: list[Message] | list[dict[str, Any]] | None = None,
    tools: ToolSet | None = None,
    stop_when: StopCondition | list[StopCondition] | None = None,
    on_step_start: OnStepStart | None = None,
    on_step_finish: OnStepFinish | None = None,
    retry: RetryPolicy | None = None,
    on_retry: OnRetry | None = None,
    provider_options: ProviderOptions | None = None,
    reasoning: ReasoningConfig | None = None,
    signal: AbortSignal | None = None,
    **kwargs: Any,
) -> GenerateTextResult

Parameters

model · LanguageModel · required

Language model instance. Create one with a provider factory such as openai("gpt-4o"), anthropic(...), or google(...).

prompt · str | None

Convenience user prompt. If messages is not provided, prompt is converted to a user message.

system · str | None

Optional system prompt. Only used when messages is not provided.

messages · list[Message] | list[dict[str, Any]] | None

Explicit message list. When provided, prompt and system are ignored.

tools · ToolSet | None

Mapping of tool name to Tool. Tool definitions are usually created with @tool.

stop_when · StopCondition | list[StopCondition] | None

Stop condition or list of stop conditions for the tool loop. Defaults to step_count_is(1).

on_step_start · OnStepStart | None

Called before each provider request. May return StepControl to inject messages or stop at a step boundary.

on_step_finish · OnStepFinish | None

Called after each step completes, including tool calls and tool results.

retry · RetryPolicy | None

Provider-call retry policy. By default, retries are conservative: transient HTTP statuses (408, 409, 425, 429, 500, 502, 503, 504) and network/timeout failures are retried; clear client errors such as 400, 401, and 403 are not. Retries happen at the current model step and do not re-run completed tools.

on_retry · OnRetry | None

Called before a retry attempt with the step number, attempt, delay, and sanitized error string.

provider_options · ProviderOptions | None

Provider-specific options keyed by provider name.

reasoning · ReasoningConfig | None

Provider-agnostic reasoning controls such as effort or budget.

signal · AbortSignal | None

Abort signal used to cancel the generation loop, including in-flight provider calls, retry sleeps, embeddings, and async tool calls.

**kwargs · Any

Additional provider-specific keyword arguments passed to the provider call.

Returns

GenerateTextResult · GenerateTextResult

Completed text generation result.

Fields:

text · str

Accumulated generated text.

steps · list[StepResult]

Step-by-step model/tool loop history.

finish_reason · str | None

Provider finish reason for the final response.

usage · Usage | None

Provider-reported usage for the final model step.

response · dict[str, Any]

Raw provider response metadata used by the provider implementation.

provider_metadata · dict[str, Any]

Additional provider metadata.

Computed properties:

tool_calls · list[ToolCall]

Flattened tool calls from all steps.

tool_results · list[ToolResult]

Flattened tool results from all steps.

Raises

ValueError · Exception

Raised when neither prompt nor messages is provided.

AbortError · Exception

Raised when signal is aborted.

RuntimeError · Exception

Raised if the generation loop exits without a final result.

Examples

Basic call

result = await generate_text(
    model=openai("gpt-4o"),
    prompt="What is Python?",
)

print(result.text)

Explicit messages

from ai_query.types import Message


result = await generate_text(
    model=model,
    messages=[
        Message(role="user", content="My name is Ada."),
        Message(role="assistant", content="Nice to meet you, Ada."),
        Message(role="user", content="What is my name?"),
    ],
)

Tool loop

result = await generate_text(
    model=model,
    prompt="Search the docs and summarize installation.",
    tools={"search_docs": search_docs},
    stop_when=step_count_is(5),
)

Step control

from ai_query import StepControl
from ai_query.types import Message


async def on_step_start(event):
    if event.step_number == 2:
        return StepControl(
            inject_messages=[Message(role="user", content="Keep the final answer short.")]
        )
    return None


result = await generate_text(
    model=model,
    prompt="Research this topic.",
    tools=tools,
    on_step_start=on_step_start,
)

Retry provider failures

from ai_query import RetryPolicy


async def on_retry(event):
    print(f"retrying step {event.step_number}, attempt {event.attempt}")


result = await generate_text(
    model=model,
    prompt="Summarize the incident.",
    retry=RetryPolicy(max_attempts=3),
    on_retry=on_retry,
)

See Also

• stream_text
• Results
• Stop Conditions
• Tool Loops