generate_text

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,
    metadata: Mapping[str, Any] | None = None,
    **kwargs: Any,
) -> GenerateTextResult

Parameters

LanguageModel

required

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

str | None

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

str | None

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

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

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

ToolSet | None

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

StopCondition | list[StopCondition] | None

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

OnStepStart | None

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

OnStepFinish | None

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

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.

OnRetry | None

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

ProviderOptions | None

Provider-specific options keyed by provider name.

ReasoningConfig | None

Provider-agnostic reasoning controls such as effort or budget.

AbortSignal | None

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

Mapping[str, Any] | None

Application metadata exposed as an immutable mapping on injected ToolExecutionContext values. It is not sent to the provider.

Any

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

Returns

GenerateTextResult

Completed text generation result.

Fields:

str

Accumulated generated text.

list[StepResult]

Step-by-step model/tool loop history.

str | None

Provider finish reason for the final response.

Usage | None

Provider-reported usage for the final model step.

dict[str, Any]

Raw provider response metadata used by the provider implementation.

dict[str, Any]

Additional provider metadata.

TurnTermination | None

Structured framework-level reason the loop ended. Inspect this instead of inferring step limits, hook stops, or tool termination from empty text.

Computed properties:

list[ToolCall]

Flattened tool calls from all steps.

list[ToolResult]

Flattened tool results from all steps.

Raises

Exception

Raised when neither prompt nor messages is provided.

Exception

Raised when signal is aborted. The exception carries termination when the runtime can attach structured diagnostics.

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,
)

Core Functions

Agent Classes

Transport Layer

Providers

Types

Import

Signature

Parameters

Returns

Raises

Examples

Basic call

Explicit messages

Tool loop

Step control

Retry provider failures

See Also

​Import

​Signature

​Parameters

​Returns

​Raises

​Examples

​Basic call

​Explicit messages

​Tool loop

​Step control

​Retry provider failures

​See Also

Import

Signature

Parameters

Returns

Raises

Examples

Basic call

Explicit messages

Tool loop

Step control

Retry provider failures

See Also