# The agentic loop

The Foldspace SDK runs the same evaluate-act-repeat agent loop that powers the Claude Agent SDK, chaining multiple actions until the request is done.

A user prompt doesn't get answered in a single pass. Foldspace runs an *agentic loop*: it evaluates the prompt against real-time context, makes one or more action calls, feeds each action result back into its next evaluation, and repeats until there's nothing left to call. This is the same loop that powers the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/agent-loop) — the Foldspace SDK runs it inside your product, grounded in your users, your knowledge, and your actions.

## Core concept

A single prompt turns into a cycle rather than a one-shot reply:

1. **User prompt** — what the user asks, in natural language.
2. **Foldspace real-time context** — the agent assembles [usage, knowledge, and action context](/guides/context/) for this turn: who the user is, the page they're on, and what it can do.
3. **Foldspace evaluates** — the agent reasons over the current state and decides the next step: make action calls, or reply.
4. **Action calls** — **one or more actions** run, and each **action result** feeds back into the next evaluation.
5. **Final reply** — when no actions are left to call, the agent answers.

The loop is what separates an agent from a chatbot. A chatbot maps a message to a response. An agent evaluates, acts on your product, reads each result, and keeps going until the prompt is actually resolved.

<AgenticLoop />

## It chains more than one action

A request rarely resolves in a single action. Within one evaluation the agent can request **several actions at once**, and across the loop it **chains many actions in sequence** — each one informed by the result of the last.

- **Multiple actions per turn.** When the agent needs several things at once, it requests them together. Independent, read-only actions can run in parallel; actions that change state run in order.
- **Many actions across turns.** A high-level request — "refund this order and email the customer" — becomes a chain: look up the order, issue the refund, then send the confirmation, with the agent re-evaluating after each result.
- **Adaptive, not scripted.** The agent decides the next action from what came back, so the same request can take a different path depending on the user, the page, and the data it sees.

This is exactly how the Claude Agent SDK behaves: a quick request might call one action, while a complex one chains many actions across turns before the agent is done.

## The same loop as the Claude Agent SDK

The Claude Agent SDK runs a cycle — evaluate, call tools, feed results back, repeat — that continues until the model responds with no tool calls. The Foldspace SDK runs that identical loop, with each stage bound to the parts of your product the agent is embedded in.

| Claude Agent SDK stage | What the Foldspace SDK does |
| :--- | :--- |
| **Receive prompt** | Takes in the request with its [assembled context](/guides/context/) — who the user is, the page they're on, the facts it can draw on, and the actions available. |
| **Evaluate and respond** | Reasons over the current state and either calls **one or more [actions](/guides/build-actions/)** or produces a reply. |
| **Execute tools** | Runs each action's [`execute()` handler](/guides/executing-actions/), fetching data or [rendering an interactive component](/guides/in-chat-ui/) in the chat, and feeds the result back. |
| **Repeat** | Cycles through evaluation and execution, chaining actions across turns until no further action is needed. |
| **Return result** | Delivers the final reply once the agent responds with no more actions to run. |

Because the loop shape is the same, patterns you know from the Claude Agent SDK carry over: give the agent good context, expose the right actions, and let it iterate.

## How the loop runs

### Evaluate

The agent doesn't load everything up front. For each pass it assembles *only* the context relevant to the request — usage context (identity, subscription, live page), knowledge context (the facts it answers from), and action context (what it can do) — and reasons over it to decide the next step. See [Context](/guides/context/) for how each source is wired up.

### Act

When the agent decides to act, it extracts the parameters each action needs from the user's intent and calls it — often more than one at a time. An action can run pure logic and return data for the agent to reason over, or [render UI in the chat](/guides/in-chat-ui/) — a form, card, or dashboard — when the request calls for interaction.

### Repeat

Each action's result feeds back into the next evaluation. The agent chains as many actions as the request needs — query, refine, confirm, execute — re-evaluating after each one. Where a step needs the user, an action can [pause for input](/guides/executing-actions/) with `awaitUserInput` before the loop continues.

### Finish

The loop ends when the agent responds with no further actions to run, or when an exit condition is met — the user saves or cancels, required inputs are collected, or a safeguard halts a repetitive cycle. Built-in loop-termination safeguards keep the agent from running indefinitely.

## Why it matters

The agentic loop is why the same intent can resolve different ways depending on who's asking and what they're doing. Instead of hard-coding one path per request, you give the agent context and actions, and the loop composes the steps — chaining as many actions as it takes — at runtime: adaptive when the situation calls for it, and deterministic where you need a fixed order.

## Related

- [Context](/guides/context/) — the three kinds of context the agent evaluates each pass.
- [Execute actions](/guides/executing-actions/) — the handler behind each action the agent runs.
- [How our agent thinks, acts, and prevents loops](/guides/agentic-capabilities/) — planning, tool selection, and termination in more detail.