---
title: 'AI Agent'
description: 'Give the AI a goal and a set of your connections as tools; it decides which to call and works toward the goal in a bounded loop.'
---
# 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.