Class AiAgent

Add a tool to the agent's tool registry. Every subsequent sendMessage(...) exposes the accumulated tools to the model. Inline literals get their executor's args parameter typed via FromSchema<S> — the same inference trick B.ai.call and B.ai.tool.custom() use. Tools produced by B.ai.tool.custom() / forNewEntry / forExistingEntry pass through as AiTool. Returns this agent for chaining.

Applies the user-reviewed (and possibly modified) tool calls produced by a stub-mode sendMessage(message, false). Each entry's name is looked up in this agent's tool registry and its executor is invoked with the entry's arguments. Returns an array mirroring the toolCalls shape: {name, arguments, result, isError}[]. Tools the agent doesn't know about produce an isError: true entry rather than throwing.

chatHistory is NOT mutated. sendMessage(message, false) and applicator(...) are both transparent to the agent's conversation history — the user message that triggered the stub, the assistant's tool_use turn, and the real tool_results are all left out. If you want a subsequent sendMessage(...) to see the round trip, call setChatHistory([...prior, {role: "user", content: message}, {role: "assistant", content: "<summary of what you applied>"}]) before the next call. The summary is what the model will treat as ground truth, so write it to reflect what the script actually applied (not what the model originally proposed, if the user edited the arguments).

Returns a snapshot of the agent's current chat history. Mutating the returned array does not affect the agent.

Remove a tool from the agent's tool registry by name. No-op when no tool with that name is registered. Returns this agent for chaining.

Send a user message through the configured agent. Builds a fresh AiCallOptions from the agent's current state (provider, model, apiKey, flag, systemPrompt, tools, chatHistory, onTurn) plus the supplied message, dispatches through the same usage-gated B.ai.call pipeline, and returns the resulting AiCallResult. When the call returns a non-blank assistant text response, the outgoing user message and that response are appended to the agent's chatHistory so subsequent sendMessage(...) calls continue the conversation. Denied calls (result.denialCode set) and calls that return blank text leave chatHistory untouched.

Two-phase variant for the review-and-apply workflow. When executeTools is false, the model still runs the full inner-loop conversation but every tool the model emits is stubbed with a "action queued" result instead of running the JS executor; the stub is fed back so the model can chain further queued calls. The returned AiCallResult.toolCalls lists every queued action ({name, arguments, result: "action queued", isError: false}) so the script can serialize them, present them to the user for review/modification, and then dispatch the real executors via applicator(...).

When executeTools is true, behavior is identical to the 1-arg sendMessage(message). When executeTools is false, the agent's chatHistory is not mutated — the conversation is mid-flight and the script owns state across the round trip.

Set an API key to call the provider directly. When present, every sendMessage(...) bypasses the web-global usage gate (no preflight, no metering). Returns this agent for chaining.

Replace the conversation history. Pass [] (or null) to reset. After each sendMessage(...), the outgoing user message and the assistant's text response are appended automatically, so this setter is mainly useful for seeding a prior conversation or wiping it between sessions. Returns this agent for chaining.

Set the usage gate tracking flag (e.g. "marketingModule"). Returns this agent for chaining.

Set the AI model identifier. Falls back to the provider's configured default when unset. Returns this agent for chaining.

Set the per-turn continuation callback used by every sendMessage(...) on this agent. Pass null to clear. After each completed assistant turn (no outstanding tool calls), the callback is invoked with the response; return an AiTurnDecision with a message to continue, or {done: true} / null to stop. Returns this agent for chaining.

Set the AI provider name (e.g. "anthropic"). Falls back to the configured tenant default when unset. Returns this agent for chaining.

Set the system prompt sent on every sendMessage(...). When provided, replaces the configured tenant default; per-call agent directives are still appended. Returns this agent for chaining.