HarnessBuild
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.
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:
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)],
});
instructionsandinputare required; the SDK does not fill them in fromcontext.inputcan 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
replytool to Desk; text the model writes on its own is only kept as a draft and never sent to the customer.
/ailo-agent #
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.
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):
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 thebodyabove plus arefissued 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: '' }:executedoes 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
executehas 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 returnedrefappears in the tool result, so the model can put it inreply'sclaims. To choose what is recorded, writeexternal: { 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>), callscope.recordExternal({ requestId, name, content, record })in the tool.recordis{ category: 'knowledge', query?, entries }, with only refs inentries, 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.acceptedisfalseand 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 #
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), sobeforeSendhooks still apply. Elsewhere inmain, passcontext, handle. - Request ids are generated in order (
sdk:<turn_id>:<kind>,.2,.3…) and stay the same when the samemainis 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
mainreturns.
/ticket #
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 #
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 isacceptedwithstatus === 'sent_for_review';review_refnames the reply under review.AiloAskReply: the reply fields the review reads,text,confidence,topic,sensitive,claimsandsources.- 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_resolvedturn: its tickets show only the confirmation tickets answered for it, the answer in theirpublic_summary. Its reply goes withpurpose: 'resume_result', as agroup_resolvedturn'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_releasedturn: the model reads what the specialist and the customer said and speaks only if the customer still needs something; otherwise it callsfinishand sends nothing. Its reply keepspurpose: 'reply'.
/trace #
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?)recordsfnas one step and returns whatfnreturns. Name it with lowercase letters, digits,_,.and-, 64 characters at most, such aslookup_order; any other character becomes_, and a name with nothing left is recorded asunnamed. Aspaninside it is a child step. Whenfnthrows, the step is marked as failed with the error's name (and aHostError'scode), 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,errorTypeandhttpStatus. The server drops any other key,gen_ai.*included. Every value butpayloadis cut to 1024 characters.payload(value)turns a value into the JSON stringATTR.payloadtakes. 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.initTraceandflushTraceare 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),spanonly runsfnand records nothing. - Uploaded code packages do not run in live conversations yet, so this path is only exercised in tests for now.