task.ts

These files define the system (TaskRunner) that manages how your agent runs asynchronous operations, especially the handler functions inside your custom action definitions. Think of it as a queue manager that prevents your agent from trying to do too many things at once, particularly when actions involve waiting for external APIs or services.

How it Affects You

You don't directly use the TaskRunner or the task function yourself. However, its existence impacts how you write your action handlers:

• Concurrency: By default, the agent only runs a few action handlers simultaneously (e.g., 3). If the AI model asks the agent to perform many actions quickly, some will wait in a queue managed by the TaskRunner before they start executing. This prevents overwhelming external services.
• Asynchronous Code: Because actions are run through this system, your action handlers must use async and await correctly if they perform any operations that take time (like network requests fetch, database calls, or even just setTimeout). The TaskRunner waits for the Promise returned by your async handler to finish.
• Retries: You can add a retry option when defining an action. If the action's handler fails (throws an error), the TaskRunner will automatically try running it again a few times. If you use this, try to make your handler logic idempotent (safe to run multiple times with the same input).
• Cancellation: Long-running actions should check for cancellation signals. Inside your action handler, the ctx object contains an abortSignal. You should check ctx.abortSignal.aborted periodically in long loops or before/after long waits and stop execution if it's true. This allows the agent's overall run to be cancelled cleanly if needed.

Benefit

The TaskRunner automatically handles concurrency limits and retries for your actions, making your agent more stable and preventing it from accidentally overloading external systems you interact with. It ensures asynchronous operations are managed correctly within the agent's lifecycle.

Anticipated Questions

• "Do I need to create a TaskRunner?" No, createDreams creates one for you automatically with default settings.
• "How do I know when my action handler actually runs?" It runs shortly after the AI model calls the action, but it might be delayed slightly if the TaskRunner's queue is busy with other actions. Use agent.logger inside your handler to see when it starts and finishes.
• "What if my action needs to run for a very long time?" Make sure to implement the cancellation check using ctx.abortSignal.aborted so the agent can stop it if necessary.