handler coroutine the host runtime invokes when the LLM calls the tool. Scope identifiers (user_id, customer_id, conversation_id) are closed over inside the handler so the LLM cannot accidentally drop them. The per-user privacy filter holds regardless of what the model passes at call time. Prefer sdk.fetch(...) as the default integration; reach for as_tool only when the LLM genuinely needs agency over when context is fetched mid-reasoning.
Parameters
Which scope the tool fetches from. One of
"conversation", "user", "customer", "client", or "unified" (cross-scope). Defaults to "user".Closed-over user identifier. Required when
scope="user", and strongly recommended for "conversation" and "unified" so the per-user privacy filter applies.Closed-over customer identifier. Required when
scope="customer". Required on B2B. Not accepted on B2C: passing it is rejected with HTTP 400. See B2C vs B2B.Optional closed-over conversation identifier. When provided, the tool always fetches for this conversation; when omitted, the LLM supplies it per call. Must be a valid UUID registered via
record_message.Override the tool description. Defaults to a scope-specific blurb that primes the LLM to call it for context retrieval.
Output dict shape.
"openai" returns {"type": "function", "function": {...}}; "anthropic" returns {"name", "description", "input_schema"}. Defaults to "openai".Returns
A tool definition dict shaped for the requestedstyle. The dict always carries an async handler key with the bound coroutine; host runtimes that don’t use it can ignore it.
Async coroutine the host runtime should
await with the LLM’s tool-call arguments. Returns the same shape sdk.fetch(...) produces.Example
Raises
InvalidInputError: whenscopeis not one of the accepted values, whenscope="user"is requested withoutuser_id, whenscope="customer"is requested withoutcustomer_id, or whenstyleis not"openai"or"anthropic".
See also
- fetch: the recommended pre-fetch integration path.
- initialize: required before calling
as_tool’s handler.
JavaScript: as a tool definition
as_tool() returns a tool definition with the scope identifiers closed over, so the model chooses the query but never whose memory to read.