The hooks
Hooks are the main API. Each one sends one stage and returns aXenoviaResponse. Hooks never skip work for you: check the response and act on it.
Every hook also accepts
session_id=.
payload["arguments"]; a redacted tool result, memory write, or reply returns masked text in payload["content"] or payload["response"].
If your model calls already go through the agent endpoint, leave
model_pre and model_post off: the runtime checks the model request and reply there. Use them only for agents that call their model provider directly.model_pre accepts messages with string content or a list of content parts (OpenAI or Anthropic style), and tools as flat {name, description} objects or OpenAI function tools. Only text is checked: text parts, refusal parts, and the text of Anthropic tool_result, mcp_tool_result and search_result blocks (string content or nested text parts) are joined. Media and file parts, the model’s own tool calls (tool_use, server_tool_use, mcp_tool_use) and thinking, and Anthropic server tool results (web search, web fetch, code execution) are not sent, so their content is not checked. On success, payload["messages"] and payload["tools"] are your own objects, with any redaction written back into the part it came from.
model_pre, and model_post when you pass messages, raise ValueError, and send nothing, when messages are not a list of dicts, a role is not a string, content is not a string, a list, or None, or a content part is malformed or of a type not listed above. model_pre also raises it when a tool is not a dict or has no name.
execute() — a single check
execute() is the call the hooks are built on. Use it for actions that are not a tool, memory, or model step.
stage is one of model_request, model_response, tool_call, tool_result, memory_write, or context_summary. If operation is omitted, the SDK uses the caller’s module.function name. execute() also accepts session_id= and turn= (see Sessions).
capability= was renamed to operation= in 0.2.0. It still works on execute() and @guard() as a deprecated alias and emits a DeprecationWarning.@guard() — decorator
@guard() checks a function call as a tool_call before the body runs. The decorated function returns a XenoviaResponse; read .result for the function’s return value.
- The payload sent is
{"arguments": {...}}, with every bound argument (including defaults). - On
allow, the function runs with its original arguments. Onredact, it runs with the masked arguments. Ondenyorerror, it does not run. async deffunctions are supported.mode="enforce"is the only mode. The SDK has no observe mode: to trial a rule without blocking, set the policy or guardrail to Monitor in the console. Monitor evaluations returnallow.
Sub-agents
To give one step of your agent its own checks, create an inline sub-agent and a key scoped to it, then use that key for the step’s client:subagent() returns a client with the same key, its own session, and the parent’s settings. It does not change which rules apply. Don’t pass it role=: that sets agent_role, which the runtime refuses.
What next?
Reference
XenoviaResponse, sessions and errors.
Sub-agents
Give a step its own key and guardrails.