# Ailo SDK

`@ailodesk/ailo-sdk` is the library for writing `main(context, handle)`: a ready-made model loop, tool definitions, ways to ask Desk for actions, and all of `main`'s types. It is optional; you can call `handle` directly without it. The SDK holds no credentials and has no global "current conversation"; everything it does goes through the `handle` you pass in.

The platform's standard package, `@ailodesk/harness-standard`, is written with this SDK.

::: note How to get it today
The SDK lives in the ailodesk repository under `packages/ailo-sdk` and is not yet published as an npm package you can install on its own. Custom code packages cannot run in live conversations yet either; see [Code packages and main](code-packages.md).
:::

## Subpaths

The root `@ailodesk/ailo-sdk` exports everything below, so existing imports keep working; new code imports the subpath it needs.

| Subpath | What it is for | Main exports |
| --- | --- | --- |
| [`/ailo-agent`](#ailo-agent) | Running the model loop | `runAgent`, `createAiloAgent`, `defineTool`, `validate`, `platformTools`, `ToolError`, limit handlers, the protocol types of `main` |
| [`/event`](#event) | Asking Desk directly, outside the loop, to send a message, hand off to a person or show progress | `createEvents` |
| [`/ticket`](#ticket) | Opening assist tickets and reading the ticket snapshot taken when the turn started | `createTickets`, `listTickets` |
| [`/ailo-ask`](#ailo-ask) | Telling whether a reply went to "Ailo asks you" for review | `isPendingReview`, the type `AiloAskReply` |
| [`/trace`](#trace) | Writing the package's own steps into this turn's run record | `span`, `ATTR`, `payload` |

Requests made through `/event` and `/ticket` are the same requests the platform tools make inside the loop, and Desk judges them by the same rules.

## Quickstart

An Ailo that answers opening hours. `hours` is the package's own tool; `platformTools(context)` adds the platform tools for replying, handing off, opening tickets and finishing:

```ts [main.ts]
import { defineTool, type Main, platformTools, runAgent } from '@ailodesk/ailo-sdk';

/** Fictional public data: a real outside adapter should return a similarly narrow projection. */
export const hours = defineTool({
  name: 'hours',
  description: 'Read the fictional demo opening hours.',
  input_schema: { type: 'object', properties: {}, additionalProperties: false },
  strict: true,
  readOnly: true,
  parse: (input) =>
    input && typeof input === 'object' && !Array.isArray(input) && !Object.keys(input).length
      ? { success: true, data: {} }
      : { success: false, issues: ['Expected an empty object.'] },
  execute: async () => ({ body: { ok: true, hours: '09:00–17:00' } }),
  external: 'demo.hours',
});

export const main: Main = (context, handle) =>
  runAgent(context, handle, {
    instructions:
      'Help with this fictional shop. Use hours for opening hours; reply through the reply tool.',
    input: 'What are your hours?',
    tools: [hours, ...platformTools(context)],
  });
```

- `instructions` and `input` are required; the SDK does not fill them in from `context`. `input` can be a string or a full message array (keeping text and image blocks).
- Only the tools you pass in are dispatched.
- Anything said to the customer goes through the `reply` tool to Desk; text the model writes on its own is only kept as a draft and never sent to the customer.

## /ailo-agent

```ts
import { runAgent, defineTool, platformTools } from '@ailodesk/ailo-sdk/ailo-agent';
```

### runAgent options

`runAgent(context, handle, options)` runs the whole loop and returns the `MainResult` that `main` returns.

| Option | Default | Notes |
| --- | --- | --- |
| `instructions` | Required | The system prompt: a string or an array of text blocks |
| `input` | Required | This turn's input: a string or a full array of messages |
| `tools` | Required | The tools this turn may use; only these are dispatched |
| `hooks` | None | See Hooks below |
| `hookTimeoutMs` | 5000 | How long each hook may run |
| `onLimit` | From `context.engine.on_limit` | How to close when a limit is hit |
| `maxConsecutiveErrors` | 3 | How many errors in a row before closing: a batch of tools with a correctable error, or a model step that hands in nothing, each counts once; any tool that succeeds resets it. This is the package's policy; the cap on model calls belongs to the Runtime |
| `correctableCodes` | `bad_request`, `invalid_input`, `unknown_tool` | Which error codes count as errors the model can correct; they count towards consecutive errors |
| `fix(code, body)` | None | A hint for the model, added to the result when the same tool returns the same error code twice in a row |
| `lastStepReminder`, `handoffReminder`, `noActionNudge` | Platform wording | What is added for the model on the last call, when writing a handoff note, and when nothing was sent |
| `prepareDraft(draft)` | None | Adjusts a draft before a limit handler uses it |
| `redact(body)` | None | Removes fields from a tool result before the model sees it |
| `onHookError(node)` | None | Tells you a hook failed, with the node name only |

### query()

`createAiloAgent(context, handle).query()` is the same loop seen as a stream of messages. Its name and shape follow the Claude Agent SDK's `query({ prompt, options })`: `prompt` is `input`, `options.systemPrompt` is `instructions`, and the other options pass through to `runAgent` unchanged.

```ts [main.ts]
import { createAiloAgent, type Main, platformTools } from '@ailodesk/ailo-sdk/ailo-agent';
import { order } from './order.ts';

export const main: Main = async (context, handle) => {
  const ailoAgent = createAiloAgent(context, handle);
  for await (const m of ailoAgent.query({
    prompt: 'Please check fictional order DEMO-001.',
    options: {
      systemPrompt: 'Help with the fictional shop.',
      tools: [order, ...platformTools(context)],
    },
  })) {
    if (m.type === 'result') return m.result;
  }
  return { success: false, error: { code: 'no_result' } };
};
```

There are three kinds of message:

| `type` | When |
| --- | --- |
| `model` | Each time a model call returns, with a snapshot of the run |
| `tool` | When a tool's `execute` actually ran, with the result it returned (failures included) |
| `result` | Always the last one; `main` returns `m.result` as it is |

Call `query()` once per turn. Breaking out early does not stop the loop; the iterator waits for the loop to finish.

### Writing your own loop

Without `runAgent`, `createAiloAgent(context, handle)` also has `start`, `get`, `resume`, `cancel` and `recordExternal`. They are thin wrappers over the handle's methods of the same names: a request id you leave out is generated for you and stays the same when the turn is replayed; `resume` and `cancel` take the whole `run` and read `runId` and `revision` from it.

### Defining tools

`defineTool` takes its fields flat: `name`, `description`, `input_schema`, `strict` and `cache_control` are sent to the model; the rest stays in the package.

| Field | Purpose |
| --- | --- |
| `execute(input, scope)` | Runs the tool and returns `{ body: { ok, … }, status?, operation_id?, end? }` |
| `parse` | Validates the model's arguments. `validate(zodSchema)` turns any Zod schema into a validator and infers `execute`'s input type. Without it the input goes to `execute` as it is; the JSON Schema alone triggers no validation |
| `readOnly` | A read-only tool. Left out, the tool is treated as a write |
| `external` | Records a successful result as evidence a reply can cite; see the next section but one |
| `timeoutMs` | The tool's timeout; without it, the turn's deadline applies |

A complete fictional order tool (uses Zod):

```ts [order.ts]
import { defineTool, validate } from '@ailodesk/ailo-sdk';
import { z } from 'zod';

const schema = z.object({
  order_id: z.string().min(1, 'Order ID is required').max(64),
}).strict();
const { $schema: _, ...input_schema } = schema.toJSONSchema();
export const order = defineTool({
  name: 'order',
  description: 'Read a fictional shop order by its ID.',
  input_schema,
  strict: true,
  readOnly: true,
  parse: validate(schema),
  external: 'shop.order',
  async execute({ order_id }) {
    if (order_id !== 'DEMO-001')
      return { body: { ok: false, code: 'not_found' } };
    return { body: { ok: true, order_id, status: 'paid', amount: 12, currency: 'MYR' } };
  },
});
```

- `{ order_id: 'DEMO-001' }`: the model gets the `body` above plus a `ref` issued by the platform, which a reply can cite.
- `{ order_id: 'MISSING' }`: the model gets `{ ok: false, code: 'not_found' }` and can carry on.
- `{ order_id: '' }`: `execute` does not run; the model gets `{ ok: false, code: 'bad_request', issues: ['order_id: Order ID is required'] }`.

Never put raw HTTP responses, credentials or internal fields in `body`.

**When things go wrong:**

- Throw `ToolError('…')` and that text goes to the model as it is; any other exception gives the model only a fixed diagnostic.
- Once a writing tool's `execute` has started, any exception counts as "side effect unknown": every later business write in this call is frozen, leaving only reads and the platform's closing actions. When you are sure nothing was written, return `{ body: { ok: false, code: 'rejected' }, status: 'failed' }` instead of throwing.
- In a batch that mixes reads and writes, only the reads run; the rest answer `not_run`. Tools run one at a time, in order.

### Platform tools

`platformTools(context)` returns these, filtered by the actions allowed in this turn:

| Tool | What it does |
| --- | --- |
| `reply` | Hands a reply to Desk. `claims` cite refs obtained in this turn |
| `request_human` | Hands off to a person. `mode` chooses a card or a direct transfer (where the site allows it); `handoff_note` is for the teammate who takes over and only the team sees it; the optional `summary` is a one-line reason |
| `request_assistance` | Opens an assist ticket with `{ kind, goal }` |
| `finish` | Ends the turn without a message |

Plus the Desk tools allowed in this turn, whose arguments Desk validates.

### Grounding replies in evidence

Desk only accepts evidence actually obtained in this turn. What a package reads from an outside system needs a record first:

- **An ordinary tool**: write `external: 'shop.order'`. A successful result is recorded automatically and the returned `ref` appears in the tool result, so the model can put it in `reply`'s `claims`. To choose what is recorded, write `external: { name, content }`. Failed, skipped and unknown results are never recorded.
- **Knowledge search**: when one call returns several entries, each with its own ref (`faq:<name>@<version>`), call `scope.recordExternal({ requestId, name, content, record })` in the tool. `record` is `{ category: 'knowledge', query?, entries }`, with only refs in `entries`, at most 20. Desk reads each entry's title and text from the content pinned for this turn, not from what you report. When Desk refuses, `receipt.accepted` is `false` and the tool should answer `{ ok: false, code: 'lookup_rejected' }`.

### Hooks

Register hooks in `runAgent`'s `hooks`; they run in order of registration. Returning `allow` or nothing lets the step through, `modify` changes it, `deny` stops it, and `downgrade` lowers a reply's confidence.

| Node | What it can do |
| --- | --- |
| `beforeModel` | Change the appended text, or refuse this model call |
| `afterModel` | Inspect what the model returned, or refuse |
| `beforeTool` | Change the tool input (not the tool name), or refuse |
| `afterTool` | Observe the real result only |
| `beforeSend` | Change a reply, lower its confidence, or refuse |
| `onLimit` | Inspect the closing reason, or refuse to close |
| `onStop` | Observe `main`'s result only |

Each hook gets 5 seconds by default (`hookTimeoutMs`). A lowered confidence cannot be raised by a later hook. **A hook's approval never gets past Desk.**

### Closing when a limit is hit

When the calls run out or consecutive errors reach the limit, `runAgent` does not throw. It first checks for new customer messages: if there are any, it ends the turn and leaves them to the next one. Otherwise it closes according to `context.engine.on_limit`:

| `on_limit` | What happens |
| --- | --- |
| `reply_with_draft` | With a draft in hand, hands it to Desk at low confidence for review; with nobody online, hands the conversation to the team |
| `request_human` | Hands off to a person with a handoff note the model writes; without a valid note, hands to the team |
| `request_assistance` | Opens an assist ticket |
| `hand_to_team` | Hands to the team directly |

To use another policy, pass your own `onLimit(info)`, or reuse `replyWithDraft`, `requestHuman`, `requestAssistance` and `handToTeam`.

A handler receives `info` with `reason` (why the turn is closing), `draft` (the draft in hand, if any) and `handoff()`. When `on_limit` is `request_human`, the platform keeps the turn's last model call for writing a handoff note (`keepsHandoffCall(context)` is true; the test bench and turns with a single call keep none); `handoff()` spends that call and returns `{ note, summary? }`, `{ fell_back }` when no note came out, or `{ superseded: true }` when the customer wrote in the meantime, leaving it to the next turn.

### Older functions

`sendMessage`, `transfer` and `openTicket` have been removed; use `/event` and `/ticket`, which keep request ids stable and return Desk's receipt. `callDeskTool(handle, call)` is still fine to use.

## /event

```ts
import { createEvents } from '@ailodesk/ailo-sdk/event';

const events = createEvents(context, handle);
const receipt = await events.send({ type: 'message', text: '…', confidence: 'high' });
```

`send(event, { requestId? })` asks Desk to do one thing. There are four kinds, with the same fields as the platform tools:

| `type` | Fields |
| --- | --- |
| `message` | `text` (1–4000 characters), `confidence` (`high` / `medium` / `low`); optional `topic` (≤40 characters), `sensitive`, `claims` (up to 10 `{ about, ref }`, where `about` is `time` / `amount` / `outcome` / `no_record`). A few more optional fields (`sources`, `ui` and others) are not covered on this page |
| `request_human` | Optional `mode` (`suggest` shows a card / `immediate` transfers directly), `handoff_note` (≤4000 characters, visible to the team only), `summary` (a one-sentence reason of ≤120 characters; an invalid one is dropped and the handoff still goes ahead) |
| `activity.started`, `activity.finished` | `activity_id`, `category` (`processing` / `knowledge` / `account` / `procedure`); optional `key`, `key_kind` |

**The receipt:**

| Outcome | Fields |
| --- | --- |
| Accepted | `accepted: true`, with `status` `sent`, `sent_for_review` (sent to "Ailo asks you", see [/ailo-ask](#ailo-ask)) or `recorded`. A handoff also carries `team_available`, `requested_mode` and `effective_mode` (where the site does not allow direct transfer, `immediate` becomes `suggest`) |
| Refused | `accepted: false`, `status: 'discarded'`, and a `code` saying why |

**Keep in mind:**

- Inside a tool, pass its `scope`: `createEvents(scope)`, so `beforeSend` hooks still apply. Elsewhere in `main`, pass `context, handle`.
- Request ids are generated in order (`sdk:<turn_id>:<kind>`, `.2`, `.3`…) and stay the same when the same `main` is replayed, so Desk recognises a repeat. Keep the order of requests within a turn fixed; when you retry yourself, pass the first id as `{ requestId }`.
- When the outcome is uncertain, it throws `HostError('turn_stopped')` and nothing more may be sent this turn.
- Ending the turn is not an event: the Runtime handles it after `main` returns.

## /ticket

```ts
import { createTickets, listTickets } from '@ailodesk/ailo-sdk/ticket';

const receipt = await createTickets(context, handle).open({
  tasks: [{ kind: 'refund_check', goal: 'Check whether order DEMO-001 can be refunded.' }],
});
```

`open({ tasks }, { requestId? })` opens one assist ticket with at least one task:

| Task field | Notes |
| --- | --- |
| `kind` | The task type, 1–64 characters |
| `goal` | What the teammate should get done, 1–1000 characters |
| `depends_on` | Optional: the tasks in the same ticket it depends on, counted from 0 |
| `required_evidence` | Optional: evidence the teammate should hand back, `{ key, ref?, value? }`, with `value` up to 200 characters |
| `allowed_actions` | Optional: actions the teammate may take |

An accepted receipt carries `task_refs`. As with `/event`: pass `scope` inside a tool, request ids are stable, and an uncertain outcome throws `HostError('turn_stopped')`.

`listTickets(context)` returns `{ tickets, as_of_version }`: the tickets Desk saw when the turn started, each with `ref`, `public_title`, `public_status` and possibly `public_summary`. It is a snapshot, not live status, and must not be told to the customer as live progress. Live reads are not available yet.

## /ailo-ask

```ts
import { isPendingReview } from '@ailodesk/ailo-sdk/ailo-ask';

if (isPendingReview(receipt)) {
  // The reply was not sent to the customer; it is waiting for a teammate
}
```

- `isPendingReview(receipt)` is true when the receipt is `accepted` with `status === 'sent_for_review'`; `review_ref` names the reply under review.
- `AiloAskReply`: the reply fields the review reads, `text`, `confidence`, `topic`, `sensitive`, `claims` and `sources`.
- Whether a reply goes to review is Desk's decision by the site's rules; a package can neither force a review nor skip one.
- Once a teammate answers, Desk opens a `review_resolved` turn: its tickets show only the confirmation tickets answered for it, the answer in their `public_summary`. Its reply goes with `purpose: 'resume_result'`, as a `group_resolved` turn's does; `replyPurpose(context)` gives it, and the platform tools and limit handlers already use it.
- When a specialist hands the conversation back, Desk opens a `human_released` turn: the model reads what the specialist and the customer said and speaks only if the customer still needs something; otherwise it calls `finish` and sends nothing. Its reply keeps `purpose: 'reply'`.

## /trace

```ts
import { ATTR, payload, span } from '@ailodesk/ailo-sdk/trace';

const order = await span('lookup_order', async (s) => {
  const r = await lookup(orderId);
  s.setAttributes({ [ATTR.outcome]: r.found ? 'found' : 'none', [ATTR.count]: r.items.length });
  s.setAttribute(ATTR.payload, payload({ status: r.status }));
  return r;
});
```

- `span(name, fn, attributes?)` records `fn` as one step and returns what `fn` returns. Name it with lowercase letters, digits, `_`, `.` and `-`, 64 characters at most, such as `lookup_order`; any other character becomes `_`, and a name with nothing left is recorded as `unnamed`. A `span` inside it is a child step. When `fn` throws, the step is marked as failed with the error's name (and a `HostError`'s `code`), never its message, and the error is thrown on to you.
- `ATTR`: the attribute keys the run record keeps, `step`, `outcome`, `code`, `ref`, `count`, `latencyMs`, `tool`, `retries`, `payload`, `errorType` and `httpStatus`. The server drops any other key, `gen_ai.*` included. Every value but `payload` is cut to 1024 characters.
- `payload(value)` turns a value into the JSON string `ATTR.payload` takes. Over 16 KiB it becomes `{"withheld":"size"}`; a value that does not serialize becomes `{"withheld":"unserializable"}`.
- The package sets nothing up and sends nothing by hand. The platform connects this turn's export before it loads the package, and once the package ends it spends up to 2 more seconds sending what is left; neither the reply nor the package's outcome waits for it. OpenTelemetry's own `trace.getTracer()` works the same way. `initTrace` and `flushTrace` are for the Runtime; a package does not call them.
- Every step lands under this package call. The organization, conversation, turn and parent named in a request do not count, and a turn keeps at most 200 steps.
- A step that cannot be written (an expired grant, a rate limit, no network) is lost on its own; the reply is unaffected and the package never fails because of it.
- Without this turn's export, as in a local run, an eval, a unit test or the platform's standard package (which runs in the server's process and keeps reporting steps through `handle.report`), `span` only runs `fn` and records nothing.
- Uploaded code packages do not run in live conversations yet, so this path is only exercised in tests for now.

## Next

- [The Runtime and run records](runtime.md)
- [Code packages and main](code-packages.md)
