handlers.ts

This file holds the internal "handlers" that the Daydreams agent uses during its execution cycle (agent.run). When the agent receives input, or when the AI model decides to call an action or send an output, the functions in this file are responsible for processing those requests correctly. Think of it as the agent's internal dispatcher and validator.

How it Affects You

You don't call functions from this file directly. It works behind the scenes, but it's where several important things happen based on how you defined your actions, inputs, and outputs:

• Validation: When the AI model provides arguments for your action or content/attributes for your output, the code here validates that data against the schema you defined using Zod. If the validation fails, it prevents your handler code from running with bad data.
• Parsing: It parses the arguments/content provided by the AI model (which might be in JSON or XML format) into a usable JavaScript object/value before passing it to your handler.
• Template Resolution: If you use templates like {{calls[0].someValue}} in your action arguments (as described in Prompting), the resolveTemplates function here handles resolving those values before your action's handler is called.
• Handler Execution: It prepares the necessary context (including the correct memory scopes like ctx.memory or ctx.actionMemory) and then calls the specific handler function you wrote in your action, input, or output definition. For actions, it uses the TaskRunner to queue the execution.
• Error Handling: It defines specific errors like NotFoundError (if the AI calls a non-existent action/output) and ParsingError (if validation fails).

Benefit

These handlers ensure that the interaction between the AI model's requests and your custom code (in action/output/input handlers) is safe, validated, and correctly contextualized. It bridges the gap between the AI's structured text output and the execution of your JavaScript/TypeScript functions, handling potential errors and data transformations along the way.

Anticipated Questions

• "Is this where my action's handler function actually runs?" Yes, functions in this file (specifically handleActionCall which uses runAction from tasks/index.ts) are responsible for preparing the context and ultimately calling the handler you defined for your action (via the TaskRunner).
• "What happens if the AI provides arguments that don't match my action's Zod schema?" The validation logic within prepareActionCall in this file will catch the mismatch, throw a ParsingError, and prevent your action's handler from being called with invalid data.
• "How does the agent know which specific context's memory (ctx.memory) to give my action handler?" The logic here (within functions like prepareActionCall and handleOutput) identifies the correct ContextState based on the current run and makes its memory available in the ctx object passed to your handler.