xr_ai_tools.tool_calling#

Helpers for dispatching model-selected native tool calls.

Attributes#

ModelCallback

Async model invocation supplied with the transcript and tool definitions.

Exceptions#

`ToolLoopError`	Base error for a turn that cannot safely produce a final answer.
`ToolLoopIterationLimitError`	The model used every permitted iteration without a final answer.
`ToolLoopToolCallLimitError`	A model batch would exceed the turn's total tool-call budget.
`ToolLoopTruncatedResponseError`	The model reported a truncated response that is unsafe to execute.
`ToolLoopEmptyResponseError`	The model returned neither a tool call nor a non-empty answer.
`ToolLoopDirectReturnError`	A model batch mixed a direct-return tool with other calls.
`ToolLoopMalformedResponseError`	The model returned tool calls that cannot form a valid transcript.

Classes#

`ToolCallResult`	One model-ready tool response and its control-flow hint.
`ToolCallRecord`	One model-requested call and the model-visible result it produced.
`ToolLoopResult`	A completed turn with its full transcript and tool-call audit.

Functions#

`tool_definitions`(→ tuple[xr_ai_models.ToolDef, Ellipsis])	Return model-service definitions for native tools.
`handle_tool_call`(→ ToolCallResult)	Invoke one model-produced call and return its tool-role message.
`run_tool_loop`(→ ToolLoopResult)	Run one stateless, bounded model turn over native tools.

Module Contents#

class xr_ai_tools.tool_calling.ToolCallResult#

One model-ready tool response and its control-flow hint.

message: xr_ai_models.ChatMessage#: Tool-role message to append to the model conversation.

return_direct: bool#: Whether the agent should return the tool result immediately.

class xr_ai_tools.tool_calling.ToolCallRecord#

One model-requested call and the model-visible result it produced.

call: xr_ai_models.ToolCall#: Model-emitted tool call that was executed.

message: xr_ai_models.ChatMessage#: Tool-role message produced for the model transcript.

return_direct: bool#: Whether this call ended the loop without another model turn.

class xr_ai_tools.tool_calling.ToolLoopResult#

A completed turn with its full transcript and tool-call audit.

content: str#: Final answer or direct-return tool content.

messages: tuple[xr_ai_models.ChatMessage, Ellipsis]#: Complete resumable transcript for the turn.

tool_calls: tuple[ToolCallRecord, Ellipsis]#: Executed tool calls in model-emitted order.

iterations: int#: Number of model iterations consumed by the turn.

return_direct: bool#: Whether the result came directly from a tool.

exception xr_ai_tools.tool_calling.ToolLoopError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: Base error for a turn that cannot safely produce a final answer.

exception xr_ai_tools.tool_calling.ToolLoopIterationLimitError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: The model used every permitted iteration without a final answer.

exception xr_ai_tools.tool_calling.ToolLoopToolCallLimitError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: A model batch would exceed the turn’s total tool-call budget.

exception xr_ai_tools.tool_calling.ToolLoopTruncatedResponseError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: The model reported a truncated response that is unsafe to execute.

exception xr_ai_tools.tool_calling.ToolLoopEmptyResponseError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: The model returned neither a tool call nor a non-empty answer.

exception xr_ai_tools.tool_calling.ToolLoopDirectReturnError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: A model batch mixed a direct-return tool with other calls.

exception xr_ai_tools.tool_calling.ToolLoopMalformedResponseError( message: str, *, messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tool_calls: collections.abc.Sequence[ToolCallRecord], iterations: int, rejected_response: xr_ai_models.ChatResponse | None = None, )#: The model returned tool calls that cannot form a valid transcript.

xr_ai_tools.tool_calling.ModelCallback#: Async model invocation supplied with the transcript and tool definitions.

xr_ai_tools.tool_calling.tool_definitions( tools: collections.abc.Iterable[xr_ai_tools.tools.Tool[Any, Any]] | xr_ai_tools.tools.ToolSet, ) → tuple[xr_ai_models.ToolDef, Ellipsis]#: Return model-service definitions for native tools.

async xr_ai_tools.tool_calling.handle_tool_call( call: xr_ai_models.ToolCall, tools: xr_ai_tools.tools.ToolSet, ) → ToolCallResult#: Invoke one model-produced call and return its tool-role message.

async xr_ai_tools.tool_calling.run_tool_loop( messages: collections.abc.Sequence[xr_ai_models.ChatMessage], tools: xr_ai_tools.tools.ToolSet, call_model: ModelCallback, *, max_iterations: int = 4, max_tool_calls: int = 16, ) → ToolLoopResult#

Run one stateless, bounded model turn over native tools.

The callback owns all model parameters and retry policy. The loop only supplies the current immutable transcript and the current turn’s tool definitions. Calls in a model batch execute sequentially in emitted order.