Agent is the stateful orchestration class in ai-query.
Use it when you need model configuration, tools, persistent state, message history, events, or transport/RPC behavior attached to a stable agent ID.
Import
Constructor
Parameters
Callback for provider reasoning events. Agent also emits these as
reasoning events.Default runtime hooks for step control, tool policy, tool result overrides, and reasoning observation.
Class Attributes
Properties
Public access to snapshots, safe message editing, event replay, and the active turn. See Agent Sessions.
start
stop
on_stop().
Context Manager
await agent.start() followed by await agent.stop().
chat
stream
chat().
run
AgentTurn and returns its structured result.
Use this when you need steps, usage, finish_reason, or output_message.
turn
events(), text_stream(), or result() is consumed. A session permits one active turn at a time.
Raises:
set_state
state event.
update_state
state event.
For Pydantic state, uses model_copy(update=kwargs) when available.
clear
emit
When
True, the event is stored in the replay log and may be returned by replay_events(). When False, the event is delivered live to connected clients but omitted from replay persistence.enable_event_log = True, events are persisted to storage.
Notes:
- Event IDs remain monotonic even for
replay=Falseevents. - Replay streams may therefore contain gaps in event IDs.
- Use
replay=Falsefor ephemeral UI commands such asopen_documentthat should not re-run on reconnect.
replay_events
id > after_id from the in-memory/persisted event log.
clear_event_log
handle_request
chatactioninvokestate
handle_request_stream
call
handle_invoke
- registered
@actionmethod - legacy
on_call_{method}handler - error response
serve
AgentServer for this agent class.