Hooks

Hooks are automated actions that run at the boundaries of a stage -- before it starts or after it completes. They execute outside the agent conversation and are used for side effects like data preparation, notifications, external system calls, or cleanup tasks.

How Hooks Work

Hooks are tied to specific stages and fire at predictable moments in the stage lifecycle:

Stage Lifecycle:
  ┌─────────────────────────────┐
  │  Entry Hooks fire            │  ← Before agents start
  ├─────────────────────────────┤
  │  Agent conversation runs     │  ← Main stage execution
  ├─────────────────────────────┤
  │  Exit Hooks fire             │  ← After agents finish
  └─────────────────────────────┘

Hooks run outside the agent conversation context. They do not participate in the multi-agent dialogue -- they are standalone tool executions that happen before or after the conversational work.

Entry Hooks

Entry hooks run before the stage's agent conversation begins. They execute in the order they are defined.

Use entry hooks for:

• Data preparation -- Fetch data from an external API and make it available to agents in the stage.
• Environment setup -- Initialize resources, create temporary files, or configure external services.
• Validation -- Check preconditions before agents start working. For example, verify that a required API is reachable.
• Notifications -- Alert a Slack channel or send an email that a workflow stage is starting.

In the Workflow Builder, entry hooks appear as small nodes docked to the left side of their stage, connected via a dashed link. A small diamond indicator on the stage's left edge signals that entry hooks are present.

Exit Hooks

Exit hooks run after the stage's agent conversation completes. They execute in the order they are defined.

Use exit hooks for:

• Result processing -- Transform or reformat the stage's output before it flows to the next stage.
• Persistence -- Save results to an external database, file system, or API.
• Cleanup -- Release resources, delete temporary files, or shut down services.
• Notifications -- Send a summary of what the stage accomplished to stakeholders.
• Metrics -- Record timing data, token usage, or quality scores.

In the Workflow Builder, exit hooks appear as small nodes docked to the right side of their stage, connected via a dashed link. A small diamond indicator on the stage's right edge signals that exit hooks are present.

Configuring a Hook

Each hook specifies:

• Tool -- Which tool to execute. This must be a tool available in the project's tool library.
• Output Key (optional) -- A label for storing the tool's result so that downstream agents and hooks can reference it.

Hooks execute a single tool call. The tool runs with the stage context available but does not have access to the agent conversation messages.

Example: Data preparation hook

An entry hook runs "Fetch Latest Metrics" before agents start. The result is stored under "metrics_data", which agents in the stage can then reference during their work.

Example: Publishing hook

An exit hook runs "Publish to CMS" after agents finish. No output key is needed because the result does not need to be passed downstream.

Multiple Hooks

A stage can have any number of entry hooks and exit hooks. They execute sequentially in the order they are defined. If a hook fails, the error is logged but subsequent hooks and stage execution continue.

Managing Hooks in the Workflow Builder

There are two ways to add hooks:

1. Drag and drop -- Drag an "Entry Hook" or "Exit Hook" card from the sidebar palette onto a stage node. This opens the stage drawer with the Hooks tab pre-selected.

2. Stage drawer -- Click a stage node to open its drawer, then navigate to the Hooks tab (tab 2). Add hooks using the add form, which presents a dropdown of available tools from the project's tool library.

The Hooks tab shows entry hooks and exit hooks in separate lists, each with add/remove controls. Hook counts are displayed in the tab label badge.

Clicking a hook node in the graph also opens the stage drawer with the Hooks tab focused.

Hooks vs Agent Phases

Hooks and agent phases (see Agents) both run at stage boundaries, but they serve different purposes:

Feature	Hooks	Agent Phases (Stage Start / Stage Complete)
Runs in conversation	No	Yes
Has access to agent tools	No (single tool call)	Yes (full tool set)
Can interact with other agents	No	Yes
Configuration scope	Stage-level	Agent-level or assignment-level
Best for	Side effects, external calls, data prep	Conversational setup/teardown, coordination

Use hooks when you need to execute a single tool call outside the conversation. Use agent phases when the setup or teardown work benefits from conversational context, multi-step reasoning, or coordination with other agents.

How-to Guides

• Configure Hooks