AI Agent

Hands the LLM a goal plus a set of tools — operations from your own connections — and lets it decide which to call, in what order, to accomplish the goal. Unlike AI Transform (one prompt, one answer), the AI Agent loops: it calls a tool, reads the result, decides what to do next, and repeats until it has an answer or hits a safety limit.

When to use

• A task that needs the AI to gather information across several APIs and then act — e.g. "Look up this player's KYC status and recent deposits, then post a risk summary to Slack."
• Open-ended investigations where you can't hard-wire the exact sequence of calls up front.
• "Reason over my connections" flows — the agent picks the right tool per input.

For a single deterministic transformation, use AI Transform. For forcing a specific JSON shape, use Structured Output. For a fixed sequence of calls, wire the API Call nodes explicitly — it's cheaper and reproducible.

Configuration

Field	Required	What it does
instructions	Yes	The agent's goal / system prompt. Supports {{...}} refs.
inputField	No	The data the agent works on. If blank, the upstream node's output is used.
tools	No	A multi-select of connection → operation pairs the agent may call. Each becomes a tool the model can invoke; OneHazel runs it through the gateway and feeds the result back. Pick from your active connections — no raw JSON.
maxIterations	No	How many reason→act cycles the agent may take (1–25, default 15). The real stop is the model deciding it's done; this is the ceiling.
memoryKey	No	Give the agent memory of prior runs for this key — see Memory below. Blank = stateless.
provider	No	groq (default) or openrouter.
model	No	Provider model ID. Default llama-3.3-70b-versatile.

How the loop works

1. The agent sends your instructions + input + the tool list to the model.
2. If the model asks to call a tool, OneHazel runs that operation through the gateway (using the connection you selected) and returns the result to the model.
3. Steps 1–2 repeat until the model returns a final answer or the iteration ceiling is reached.
4. Each tool has its own retry cap, and a hard recursion bound sits above maxIterations — a misbehaving agent can't loop forever.

Memory (optional)

Set a Memory Key — typically a template like {{trigger.data.player_id}} — and the agent remembers prior turns for that key across separate runs. The next run for the same key sees the previous conversation, so the agent has context (e.g. per-player history). Memory is best-effort: if the memory store is briefly unavailable the agent still runs, just without history. Older turns roll off a bounded window.

What it outputs

{
  output: "the agent's final answer",
  result: "same as output",
  iterations: 3,
  aiCalls: 4,
  toolCalls: 5,
  halted: null,          // or "max_iterations" if it hit the ceiling
  model: "llama-3.3-70b-versatile",
  provider: "groq",
  durationMs: 6120,
  memory: { key: "player_42", turns: 2 }   // only when a Memory Key is set
}

Downstream nodes reference {{ai_agent.data.output}}.

Gotchas

• It needs tools with data behind them. Select operations from connections that are active and authenticated — the agent can only do as much as its tools allow.
• Non-deterministic. The agent may take a different path on each run. Don't use it where you need a reproducible sequence.
• Cost. Each cycle is an AI call, and each tool run is an API call — both count toward your usage. Keep maxIterations sane for the task.
• Prompt injection. If the input contains untrusted user text, it can try to steer the agent. Be explicit in your instructions about what the agent may and may not do.