HarnessBuild

Ailo SDK

Updated 2026-11-12Partly available

@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.

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.

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 Running the model loop runAgent, createAiloAgent, defineTool, validate, platformTools, ToolError, limit handlers, the protocol types of main
/event Asking Desk directly, outside the loop, to send a message, hand off to a person or show progress createEvents
/ticket Opening assist tickets and reading the ticket snapshot taken when the turn started createTickets, listTickets
/ailo-ask Telling whether a reply went to "Ailo asks you" for review isPendingReview, the type AiloAskReply
/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:

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 #

TypeScript
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.

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):

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 #

TypeScript
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) 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 #

TypeScript
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 #

TypeScript
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 #

TypeScript
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 #