> ## Documentation Index
> Fetch the complete documentation index at: https://agents.candu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Candu Actions works

> Understand the three-layer architecture connecting your app, Candu's orchestration layer, and your API, including how tool calls execute client-side.

```
Configuration
  actions.json · agent.json · segment-wizard.json
  ↓
Candu Actions API (Claude / GPT / Gemini)
  intent matching · tool calls · agent responses
  ↓
Clientside SDK (runs inside your app)
  Chat UI · Wizard UI · First-party Snippet
  ↓
Your API: called by user's browser, with their credentials
```

## Layer 1: Configuration

Your config lives at `https://cdn.candu.ai/agentikConfig/{clientToken}/`. Three files are deployed together: `actions.json` (action registry), `agent.json` (system prompt customisation), and wizard configs like `segment-wizard.json`.

Config changes propagate via CDN — typically within 60 seconds of save. Versioning lets you roll forward or back without redeploying your app.

## Layer 2: Candu Actions API

Handles the conversation layer: receives user input, calls the AI provider, translates responses into tool calls. Fully managed. When the AI decides to call an action, it returns a structured tool call to the SDK.

## Layer 3: Clientside SDK

Runs inside your application, inside your users' browsers. The First-party Snippet is the critical piece. It intercepts tool call events from the SDK and executes the actual HTTP request using your `fetchFn` and your credentials.

```
AI decides to call segments_create
→ SDK dispatches candu-agentik:action event
→ Your snippet intercepts
→ fetch("/api/segments", { headers: { Authorization: "Bearer ..." } })
→ Your API responds
→ Snippet dispatches candu-agentik:result
→ AI continues conversation
```

## What Candu touches and what it doesn't

|                     | Candu                                | Your app                                                |
| ------------------- | ------------------------------------ | ------------------------------------------------------- |
| Conversation state  | Managed by Candu                     | —                                                       |
| AI model calls      | Managed by Candu                     | —                                                       |
| API execution       | Never                                | Your snippet, your credentials                          |
| Auth tokens         | Never sees them                      | Injected by your fetchFn                                |
| Identifiers         | Not persisted                        | Injected into AI prompt at request time, then discarded |
| API response bodies | Recorded in execution logs (as JSON) | Your API determines what's returned                     |
| Execution logs      | actionId, inputs, outputs, status    | —                                                       |