ModelRequest#

Implement the model contract and normalize usage and stream output. See the guide.

class zett_agent.model.ModelRequest(messages, tools=(), server_tools=(), reasoning_effort=ReasoningEffort.MEDIUM, tool_choice=None, parallel_tool_call=True, cache_key=None)[source]#

Complete provider-neutral input for one model step.

The runtime rebuilds this object before every model call. messages therefore includes the current system instructions, restored context, and completed tool round trips in chronological order.

Before-model hooks also receive this type. Each hook receives a fresh shallow view of context at entry; the provider receives a final rebuilt request after preprocessing. Frozen fields do not freeze nested messages.

Examples

Inspect the shape received by a custom adapter:

request = ModelRequest(
    messages=[
        SystemMessage(content="Be concise."),
        UserMessage(content="What is 20 + 22?"),
    ],
    tools=[add.definition],
    server_tools=[ServerToolDefinition(type="web_search")],
    reasoning_effort=ReasoningEffort.LOW,
)

Note

Retry policy belongs to the model adapter, not to this request. One ModelRequest describes intent; it does not control transport attempts.

See also

AgentModel defines the receiving adapter, and ToolDefinition defines exposed model tools.

Parameters:
messages: Sequence[AnyMessage]#

Fully assembled context, including instructions and tool round trips.

tools: Sequence[ToolDefinition]#

Tools exposed for this model step; empty means no tool definitions.

server_tools: Sequence[ServerToolDefinition]#

Provider-hosted tools that bypass the Agent’s local tool executor.

reasoning_effort: ReasoningEffort#

Desired reasoning level; provider capabilities determine its mapping.

tool_choice: str | None#

Optional local function name or registered server-tool type the provider must call.

parallel_tool_call: bool#

Whether the provider may return more than one local tool call in one response.

Adapters map this preference when their protocol exposes an equivalent switch. The Agent still decides whether returned calls are safe to run concurrently; this flag alone never makes local execution concurrent.

cache_key: str | None#

Routing key that lets an endpoint reuse one cached prompt prefix.

The Agent fills this from the run’s session identity, so every step of one conversation routes to the same cache. Adapters map it to their protocol; the OpenAI Chat Completions and Responses APIs both call it prompt_cache_key. None declares no key and leaves routing to the endpoint.