Hooks

Invoked when a new agent or box run starts. In boxes, it fires upon box run initiation.

Triggered when an error occurs during an agent run. If provided Scoopika will stop throwing errors and It will pass them to this hook instead.

The healed property specifies if the error was auto healed using the Auto healing feature.

Activated upon the completion of an agent run. For boxes, it’s called after each agent within the box finishes its run. Consider using onAgentResponse instead within boxes (explained later).

Reference to AgentResponse

This hook, supported in both agents and boxes, is triggered upon the completion of an individual agent run (within a box context). It delivers an object containing the agent’s name and response. This is the recommended way to handle individual agent responses within boxes as opposed to using onFinish.

Reference to AgentResponse

This hook delivers a stream of tokens (text chunks) generated by the LLM in real-time, for both agents and boxes.

Similar to onToken, but provides additional information like run_id, type (currently always “text”), and the token content itself.

StreamMessage properties:

• run_id: string.
• type: "text" | "image". currently only "text" is being used.
• content: string. the token value.
• final: boolean. not being used anymore.

Invoked whenever an agent calls an external tool before argument validation and tool execution. While it offers early insight, use with caution due to the lack of argument validation at this stage.

Reference to ToolCall

Activated when an agent calls an external tool after successful tool argument validation and execution. This hook provides details about the tool call and the returned result.

Reference to ToolHistory

Exclusive to boxes, this hook is called when a box selects an agent to handle a specific task based on factors like the run’s message field within the Inputs and the conversation history.

Reference to AgentData

Exclusive to boxes, this hook fires when the entire box run finalizes. It delivers an array containing the results (name and run response) from each agent executed within the box run.

Reference to AgentResponse