HarnessAPI reference
Knowledge and SOP API
Knowledge (FAQ), SOPs and the persona live in the Harness content table: one identity row per entry plus immutable versions. The Console pages, Orbit, the CLI and scripts all use the same named commands. This page covers three things: how to read, edit and publish them over the API; how a code package reads them during a turn; and how tool names line up.
- Saving a version changes no conversation. A turn reads only the package version it pinned when it started.
- Publishing makes a new package version and does not set it live.
set_package_live_versiondoes; rolling back is setting an older package version live again. - Tool names are the key that joins knowledge, SOPs and the SDK.
Every endpoint on this page is on main (publish, create and archive arrived with #1207; creating and editing SOPs and check_sop with #1294; both on 11-12). All ids and content in the examples are made up.
Conventions #
Every path starts with /api/tenants/{tenant_id}, where tenant_id is your organization. Another organization's package or entry always answers 404 not_found.
Authentication: send Authorization: Bearer <key> with a member's personal access key or a signed-in session. The CLI reads AILO_ACCESS_KEY or AILO_TOKEN (one of the two) and the server address from AILO_BASE_URL.
Source: x-ailo-via is api, cli, ui or copilot; without it the call counts as api.
Commands: always POST with the body { "command_id": "…", "input": { … } }. Content commands may leave out command_id and the server makes one; package commands require it. Retrying with the same command_id and the same input returns the first result; the same command_id with other input is 409 idempotency_key_reused. A refused command leaves no record, so the next try is decided afresh.
Permissions: reads need a specialist or above, and read-only keys can read (permission console.view). Editing content needs an admin (knowledge.edit); publishing needs an admin (console.publish).
| Status | code |
Meaning |
|---|---|---|
| 400 | bad_request |
The input is wrong; issues says where |
| 401 | unauthorized |
No key, or the key is not valid |
| 403 | permission_denied |
The role is too low, or a read-only key called a write |
| 404 | not_found |
The package or entry does not exist, or is not this organization's |
| 404 | unknown_command |
No content command by that name (an unknown package command returns 404 not_found) |
| 409 | idempotency_key_reused |
The same command_id came with different input |
| 409 | package_credentials_forbidden |
The content has a credential field (such as token or password) or contains a secret value this organization has stored; field says where. Key-shaped text is not guessed at |
export AILO_BASE_URL=https://api.example.com
export AILO_ACCESS_KEY=<your personal access key>
{
"command_id": "4b7e2c1a-9d3f-4e8a-b6c5-0f1e2d3c4b5a",
"input": { "content_id": "ct_7d2a", "expected_version": 3 }
}
{ "ok": false, "code": "version_conflict", "latest_version": 4 }
List content #
GET/api/tenants/{tenant_id}/packages/{package_id}/content
Every entry of one package, ordered persona, SOPs, FAQ, and by name within each kind. Query name list_content.
- Permission: specialist or above; read-only keys can call it.
- Orbit: on main, a read Orbit can run.
- CLI:
ailo content list P [--kind faq|sop|persona] [--q words]
| Parameter | Type | Required | Description |
|---|---|---|---|
kind |
string | No | faq, sop or persona |
q |
string | No | 1–200 characters, matched in the name, title or text, case-insensitive. A page filter, not Ailo's knowledge search |
Each item has content_id, kind, name, title, locales, latest_version, archived, live_version, live_differs and updated_at.
live_version: which version of this entry the live package version carries.nullwhen the live version does not have the entry, nothing is live, or the text does not match.live_differs: the live package has this name with a text that is none of the versions saved here (someone saved the package directly, around the content table).- At most 500 items; beyond that
truncatedistrueand you narrow withq.
curl "$AILO_BASE_URL/api/tenants/demo-shop/packages/pkg_demo/content?kind=faq&q=withdraw" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
pnpm ailo content list pkg_demo --kind faq --q withdraw --tenant demo-shop
{
"ok": true,
"items": [
{
"content_id": "ct_7d2a",
"kind": "faq",
"name": "withdrawal-time",
"title": "How long a withdrawal takes",
"locales": ["en", "zh-CN"],
"latest_version": 4,
"live_version": 3,
"live_differs": false,
"updated_at": "2026-11-11T02:40:12.031Z"
}
],
"truncated": false
}
Read an entry #
GET/api/tenants/{tenant_id}/content/{content_id}
One entry's latest version in full, which version is live, and its history (newest first, at most 200). Query name read_content.
- Permission: specialist or above; read-only keys can call it.
- Orbit: on main, a read Orbit can run.
- CLI:
ailo content show C
content has archived, true once the entry is archived.
content.doc is that version's document, with the fields in SOP and document fields except id and version: the name is in name and the number in latest_version.
Each version's source is import, save, create or site (imported from site files). based_on is the version it was edited from, package_version the package version it was imported from.
curl "$AILO_BASE_URL/api/tenants/demo-shop/content/ct_7d2a" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
pnpm ailo content show ct_7d2a --tenant demo-shop
{
"ok": true,
"content": {
"content_id": "ct_7d2a",
"package_id": "pkg_demo",
"kind": "faq",
"name": "withdrawal-time",
"latest_version": 4,
"live_version": 3,
"live_differs": false,
"created_by": "agt_demo_admin",
"created_at": "2026-11-10T08:00:00.000Z",
"updated_at": "2026-11-11T02:40:12.031Z",
"doc": {
"title": "How long a withdrawal takes",
"content": "Usually within 30 minutes; longer at peak times.",
"locales": ["en", "zh-CN"],
"tags": ["withdrawal"],
"tools": [],
"legacy_ids": []
}
},
"versions": [
{
"version": 4,
"source": "save",
"based_on": 3,
"package_version": null,
"note": "Mention peak times",
"doc_sha256": "9c1f…",
"created_by": "agt_demo_admin",
"created_at": "2026-11-11T02:40:12.031Z"
}
]
}
Read an older version #
GET/api/tenants/{tenant_id}/content/{content_id}/versions/{version}
One version in full, to compare or to restore it. Query name read_content_version.
- Permission: specialist or above; read-only keys can call it.
- Orbit: on main, a read Orbit can run.
- CLI:
ailo content show C --version N
To restore an older version, save its fields again as a new version (next section). Nothing moves a pointer.
curl "$AILO_BASE_URL/api/tenants/demo-shop/content/ct_7d2a/versions/3" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
pnpm ailo content show ct_7d2a --version 3 --tenant demo-shop
{
"ok": true,
"version": {
"content_id": "ct_7d2a",
"version": 3,
"source": "import",
"based_on": null,
"package_version": 2,
"note": null,
"doc_sha256": "51ab…",
"created_by": "agt_demo_admin",
"created_at": "2026-11-10T08:00:00.000Z",
"doc": { "title": "How long a withdrawal takes", "content": "Usually within 30 minutes.", "locales": ["en", "zh-CN"], "tags": ["withdrawal"], "tools": [], "legacy_ids": [] }
}
}
Import a package's content #
POST/api/tenants/{tenant_id}/content/commands/import_package_content
Copies the persona, SOPs and FAQ of one package version into the content table, one entry each, keeping their version numbers. Existing entries are skipped, never overwritten. Nothing goes live.
- Permission: admin (
knowledge.edit). - Orbit: on main, a command Orbit can run; a confirmation card or a direct run, depending on the Orbit mode.
- CLI:
ailo content import P [--version N],ailo content import P --file documents.json(thedocumentsinput below)
| Parameter | Type | Required | Description |
|---|---|---|---|
package_id |
string | Yes | The package |
version |
integer | No | The package version to import from. Default: the latest. When it is older than the latest, entries the latest carries newer come in too (from_latest in the answer), so the content table is never behind the package |
documents |
object | No | The documents file pnpm site:import writes, instead of version. New names are added (imported), changed texts get their next version (updated), unchanged ones are only counted (unchanged), and entries missing from the files are kept and listed in not_in_files |
| Status | code |
When |
|---|---|---|
| 409 | unsupported_package |
A code package or an archived one |
| 409 | package_content_required |
The package has no version yet |
After an import
Once a package's content is imported, save_package_version with documents answers 409 content_managed. The documents then change only through the commands on this page, then a publish.
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/import_package_content" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"package_id": "pkg_demo"}}'
pnpm ailo content import pkg_demo --tenant demo-shop
{
"ok": true,
"package_id": "pkg_demo",
"package_version": 2,
"imported": [
{ "kind": "persona", "name": "persona", "content_id": "ct_1b90", "version": 1 },
{ "kind": "faq", "name": "withdrawal-time", "content_id": "ct_7d2a", "version": 3 }
],
"skipped": []
}
Save a version #
POST/api/tenants/{tenant_id}/content/commands/save_content_version
Changes a few fields of the latest version and saves the result as the next version. Fields you leave out keep the latest version's values. Nothing goes live and no conversation changes.
- Permission: admin (
knowledge.edit). - Orbit: on main, a command Orbit can run; a confirmation card or a direct run, depending on the Orbit mode.
- CLI:
ailo content save C --expected-version N --file doc.json [--note text], wheredoc.jsonholds the fields to change.
| Parameter | Type | Required | Description |
|---|---|---|---|
content_id |
string | Yes | The entry |
expected_version |
integer | Yes | The latest version you read. version_conflict if someone saved first |
title |
string | No | 1–200,000 characters |
content |
string | No | The text, replaced as a whole, 1–200,000 characters |
locales |
string[] | No | Language tags such as en, 1–200 of them |
tags |
string[] | No | Letters and digits in any script (Chinese, Thai and so on), - and _, 1–64 characters each, no spaces or punctuation; at most 200 |
tools |
string[] | No | SOPs only: the tool names this SOP uses; see Tool names |
fields |
object | No | SOPs only: replaced as a whole; see SOP and document fields |
note |
string | No | What changed, 1–200 characters |
FAQ entries, the persona and SOPs can all be edited. tools or fields on an FAQ entry or the persona answers 400 bad_request. This command does not change legacy_ids or timezone.
The new number is one more than the larger of the entry's latest version and the highest number this name has in any package version, so numbers can jump. That way faq:<name>@<version> always names one text.
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
The edited document is not valid; fields lists the fields |
| 409 | version_conflict |
Someone saved first; latest_version is the current number. Read again and redo the edit |
| 409 | no_change |
The result equals the latest version |
| 409 | content_archived |
The entry is archived; restore it first |
| 400 | sop_mode_required |
fields is passed without mode: every SOP says by steps or by goal |
| 409 | sop_mode_locked |
The SOP's fields.mode differs from the latest version's: by steps and by goal never convert; mode is the current one |
| 409 | content_unreadable |
The latest version cannot be read |
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/save_content_version" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"content_id": "ct_7d2a", "expected_version": 3,
"content": "Usually within 30 minutes; longer at peak times.", "note": "Mention peak times"}}'
echo '{"content": "Usually within 30 minutes; longer at peak times."}' > doc.json
pnpm ailo content save ct_7d2a --expected-version 3 --file doc.json \
--note "Mention peak times" --tenant demo-shop
{ "ok": true, "content_id": "ct_7d2a", "version": 4, "based_on": 3 }
Add a FAQ #
POST/api/tenants/{tenant_id}/content/commands/create_content
Adds a new FAQ entry or SOP to a package. Nothing goes live. The persona cannot be created. A package whose content is not imported but has a version gets its latest version imported first; a refused create undoes that import too. A new package with no version yet has nothing to import: the entry is written as it is, and publishing waits until the package's first version is saved.
- Permission: admin (
knowledge.edit). - Orbit: a command Orbit can run. A confirmation card when Orbit suggests it; runs at once when the member explicitly asked.
- CLI:
ailo content create P --file entry.json [--note text]
| Parameter | Type | Required | Description |
|---|---|---|---|
package_id |
string | Yes | The package |
kind |
string | Yes | faq or sop. The CLI sends faq unless the file says "kind": "sop" |
name |
string | Yes | Lower-case letters, digits and -, 1–64 characters; fixed once saved |
title |
string | Yes | The title |
content |
string | Yes | The text |
locales |
string[] | Yes | Language tags, at least one |
tags |
string[] | No | Tags |
tools |
string[] | No | SOPs only; see Tool names |
fields |
object | For an SOP | SOPs only, with at least mode (steps or goal); see SOP and document fields |
note |
string | No | A note, 1–200 characters |
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
kind is neither faq nor sop, or an FAQ entry has tools or fields |
| 400 | sop_mode_required |
A new SOP without fields.mode: it must say by steps or by goal |
| 409 | name_taken |
The package already has this name |
| 409 | unsupported_package |
A code package or an archived one |
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/create_content" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"package_id": "pkg_demo", "kind": "faq", "name": "bonus-rules",
"title": "How to claim a bonus", "content": "Tap Claim on the promotion page.", "locales": ["en"]}}'
pnpm ailo content create pkg_demo --file entry.json --tenant demo-shop
{ "ok": true, "content_id": "ct_c41e", "name": "bonus-rules", "version": 1 }
Archive and restore #
POST/api/tenants/{tenant_id}/content/commands/archive_content
An archived entry is left out of the next publish; its versions stay, and after a restore the next publish carries its latest version again. No version is written. The persona cannot be archived. Restoring is restore_content, whose only input is content_id.
- Permission: admin (
knowledge.edit). - Orbit: a command Orbit can run. A confirmation card when Orbit suggests it; runs at once when the member explicitly asked.
- CLI:
ailo content archive C --expected-version Nandailo content restore C
After an archive, customers keep getting the entry until a package version without it is set live.
| Parameter | Type | Required | Description |
|---|---|---|---|
content_id |
string | Yes | The entry |
expected_version |
integer | To archive | The latest version you read |
| Status | code |
When |
|---|---|---|
| 409 | persona_required |
The persona cannot be archived |
| 409 | version_conflict |
Someone saved before the archive |
| 409 | no_change |
Already archived (or already restored) |
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/archive_content" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"content_id": "ct_c41e", "expected_version": 1}}'
pnpm ailo content archive ct_c41e --expected-version 1 --tenant demo-shop
pnpm ailo content restore ct_c41e --tenant demo-shop
{ "ok": true, "content_id": "ct_c41e", "archived": true, "version": 1 }
Publish #
POST/api/tenants/{tenant_id}/content/commands/publish_content
Publishes the content table as a new version of the package, with the latest package version's settings (and the live version's engine parameters). SOPs are published one at a time: with content_ids, those entries go in at their latest version and every other entry stays as the latest package version has it. Without it, SOPs stay at their last published version (one never published stays out) and every other entry not archived goes in at its latest version. An entry the latest package version carries newer (same name, higher number), or that the content table lacks, is taken from that version and written back to the content table first. Articles are searched by meaning only once a member has confirmed the knowledge index; until then the FAQ list is used and the reply carries warnings: [{code: 'articles_not_searched', reason: 'index_not_confirmed'}]. A version that already searches by meaning builds its index first; when it can't (no embedding model, or the models don't respond) the publish is refused with knowledge_models_unavailable or knowledge_index_failed, nothing is saved and the method and confirmation stay, so publishing again works once the models are back. Only an older version whose method the system set on its own publishes on the FAQ list instead, with that reason in warnings; a publish confirmed on an Orbit card is refused either way. It does not go live and no conversation changes; see the next section.
- Permission: admin (
console.publish). - Orbit: a command Orbit can run. A confirmation card listing each entry's version before and after when Orbit suggests it; runs at once when the member explicitly asked.
- CLI:
ailo content publish P [--ids C,C] [--remove-ids C,C] [--note text]
Before publishing, check_sop runs on every SOP that changes (see SOP and document fields); one problem refuses the whole publish and nothing is written.
| Parameter | Type | Required | Description |
|---|---|---|---|
package_id |
string | Yes | The package |
content_ids |
string[] | No | The entries to publish (one, or up to 5000 for a batch); one SOP failing its check refuses the batch. An archived one is content_archived |
remove_content_ids |
string[] | No | Disabled entries to take out of the new version (up to 5000; the removed rows of the changes); every entry not named stays as the latest package version has it, as with content_ids. One enabled again is content_not_archived |
note |
string | No | What this version changes, 1–500 characters; stored on the version (note in the version list) |
expected_versions |
object | No | {content_id: version}: each entry's latest saved version as you read it (latest_version in the changes). One saved since is content_changed, so nothing goes in unseen |
expected_content_sha256 |
string | No | The digest of the version you previewed. If content or settings changed since, content_changed. Orbit's card uses it |
Returns the new version number version, its digest content_sha256, the current live version live_version, changes (each {content_id, kind, name, from, to}; to: null means this version leaves the entry out; content_id: null is an entry the live package has but the content table does not) and config_changed (true when the settings differ from the live version's; they go live with it).
| Status | code |
When |
|---|---|---|
| 409 | content_not_imported |
The package's content has not been imported |
| 409 | content_changed |
Someone changed an entry the publish was writing back from the package; nothing was saved, try again |
| 409 | no_change |
Same as the live version; or same as the latest saved package version, then with version: set that one live |
| 409 | sop_check_failed |
problems lists each SOP's problems |
| 409 | content_changed |
Does not match expected_content_sha256, or an entry's latest version is not the one in expected_versions |
| 409 | content_not_archived |
An entry in remove_content_ids is enabled |
| 404 | not_found |
An id in content_ids, remove_content_ids or expected_versions is not this package's |
| 409 | invalid_engine_config |
The engine parameters do not read; turns on this version could only go to the team |
| 409 | package_content_required |
The package has no version yet |
| 409 | unsupported_package |
A code package or an archived one |
| 409 | content_unreadable |
An entry's latest version does not read |
| 409 | package_credentials_forbidden |
The content has a credential field (such as token or password) or contains a secret value this organization has stored; field says where. Key-shaped text is not guessed at |
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/content/commands/publish_content" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"package_id": "pkg_demo"}}'
pnpm ailo content publish pkg_demo --tenant demo-shop
{
"ok": true,
"package_id": "pkg_demo",
"version": 3,
"content_sha256": "e3a0…",
"live_version": 2,
"changes": [
{ "content_id": "ct_7d2a", "kind": "faq", "name": "withdrawal-time", "from": 3, "to": 4 },
{ "content_id": "ct_c41e", "kind": "faq", "name": "bonus-rules", "from": null, "to": 1 }
],
"config_changed": false
}
What changed and who saved it #
GET/api/tenants/{tenant_id}/packages/{package_id}/changes
With ?version=N: what version N changed against the version before it (or ?against=M), entry by entry, with its note, who saved the version and when, and settings_changed when tools or settings differ too (compare_package_versions shows those field by field). Without version: the entries saved since the latest version and not in any version yet, then the disabled entries the latest version still carries; what publish_content can put into one new version. Titles and names only, never an entry's text. Only real versions count: a 试用 version is never listed or compared.
- Permission:
console.view. - Orbit: a read Orbit can run (
list_package_changes). - CLI:
ailo packages changes P [--version N [--from M]]
Each entry is {content_id, kind, name, title, change, saves}: kind is persona, sop, faq or article; change is added, changed or removed; saves lists each member who saved it in between with the time, newest first (an import copies a version's text and names no one). A removed entry names who disabled it, or who saved the version that left it out, as recorded when that version was saved. Without version, each entry not removed also has latest_version: send it back in expected_versions.
| Status | code |
When |
|---|---|---|
| 409 | version_required |
against without version |
| 404 | not_found / package_version_not_found |
Not this organization's package, or no such version |
| 409 | unsupported_package |
A code package; or, without version, an archived one |
| 503 | changes_timeout |
The package was too large to read in time; try again |
Set live and roll back #
POST/api/tenants/{tenant_id}/packages/{package_id}/commands/set_package_live_version
Sets a saved package version live. Turns that start afterwards read it; a turn already running does not change. This is a package command and is on main.
- Permission: admin (
console.publish). - Orbit: only proposes a confirmation card; it never runs this itself.
- CLI:
ailo packages live P N --expected-revision R
Roll back: set an older package version live the same way. rollback_package_version (input expected_revision only) also exists; it can only return to the previous live version (ailo packages rollback P --expected-revision R) and needs the deploy permission (console.deploy).
Package commands require command_id. Read expected_revision from GET /api/tenants/{tenant_id}/packages/{package_id} (ailo packages show P).
| Parameter | Type | Required | Description |
|---|---|---|---|
version |
integer | Yes | The package version to set live |
expected_revision |
integer | Yes | The package revision you read |
| Status | code |
When |
|---|---|---|
| 409 | revision_conflict |
The package changed; revision is the current one |
| 409 | sop_tool_missing |
A tool an SOP needs is missing or off at a site that runs the package; missing lists them |
| 409 | too_many_resident_tools |
Resident tools exceed the platform's cap |
| 409 | invalid_engine_config |
This version's engine parameters do not read |
| 409 | no_previous_version |
A rollback with no previous live version |
curl -X POST "$AILO_BASE_URL/api/tenants/demo-shop/packages/pkg_demo/commands/set_package_live_version" \
-H "Authorization: Bearer $AILO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"command_id": "c7f0b2d4-1e3a-4c5b-9d8e-7f6a5b4c3d2e",
"input": {"version": 3, "expected_revision": 5}}'
pnpm ailo packages live pkg_demo 3 --expected-revision 5 --tenant demo-shop
# back to version 2
pnpm ailo packages live pkg_demo 2 --expected-revision 6 --tenant demo-shop
{ "ok": true, "version": 3, "content_sha256": "e3a0…", "revision": 6 }
SOP and document fields #
The persona, each SOP and each FAQ entry are the same kind of document in a package version (packageDocumentSchema in apps/server/src/package-content.ts). A package version's documents is { persona, sops[], faq[] }: at most 500 SOPs and 2,000 FAQ entries, with no id twice within a kind.
| Field | Type | Description |
|---|---|---|
id |
string | The name: lower-case letters, digits and -, 1–64 characters. Called name in the content table |
version |
integer | Version number, a positive integer |
title |
string | Title, 1–200,000 characters |
content |
string | Text, 1–200,000 characters. Called text in a code package |
locales |
string[] | Language tags, 1–200 of them |
tags |
string[] | Tags: letters and digits in any script, - and _, 1–64 characters each; at most 200 |
tools |
string[] | Tool names this SOP uses; see Tool names |
legacy_ids |
string[] | Former names, same format as id |
timezone |
string | Optional IANA time zone |
locale_timezones |
object | Optional, language tag to IANA time zone |
An SOP's fields. Besides the document above, each SOP version can store fields for the editor and the team. They live only on the content version and are not part of the package version: Ailo does not read them in a turn yet, and variables are declarations only, with no run-time assignment yet.
| Field | Type | Description |
|---|---|---|
description |
string | What the SOP does, 1–256 characters |
when_to_use, not_for |
string[] | When it applies and when it does not, up to 20 items each, 1–200 characters per item |
mode |
string | steps or goal, required: a new SOP or a save that passes fields without it is refused (sop_mode_required). Set at creation and never changed between the two (sop_mode_locked). An SOP imported from a package has none yet; its first save with fields chooses it |
triggers |
string[] | What invokes it: conversation, event, sop |
events |
string[] | Only when triggers includes event: which triggers |
variables |
object[] | Up to 50, each with name, type (string, integer, enum, date-time, boolean), options, description, required, and an optional default for booleans |
Checking an SOP: check_sop. Before a publish every SOP gets a structural check: formats and names only, no model call, and no judgement of how well the SOP is written. Any problem refuses the publish with 409 sop_check_failed {problems}. You can also check the latest version of one SOP on its own:
GET/api/tenants/{tenant_id}/content/{content_id}/check
- Permission: Specialist and above; read-only keys work (
console.view). - Orbit: can call it.
- CLI:
ailo content check C - Returns
{ ok: true, version, problems }. An entry that is not an SOP, or belongs to another organization, answers404 not_found. - Whether a tool is on at each site is not checked here; set live checks it (
sop_tool_missing).
code |
When |
|---|---|
content_empty |
The text is empty |
tool_format |
A tool name is malformed |
tool_unknown |
The tool library has no such tool |
tool_undeclared |
The text links a tool that is not in tools (Ailo's built-in tools excepted) |
procedure_unknown |
A linked SOP does not exist or is archived |
procedure_in_condition |
A condition contains another SOP |
condition_too_deep |
Conditions nested deeper than two levels |
variable_undeclared |
A variable is used but not declared in fields.variables |
export interface SopProblem {
sop: string; // the SOP's name (the package document's id)
field: string; // a field path, such as 'tools[1]', 'content' or 'content[ailo:tool/name]'
code: string; // a code from the table above
}
{
"ok": true,
"version": 2,
"problems": [
{ "sop": "withdrawal-delay", "field": "tools[0]", "code": "tool_unknown" }
]
}
{
"id": "withdrawal-delay",
"version": 2,
"title": "Handling a delayed withdrawal",
"content": "1. Check the withdrawal's status.\n2. Over 2 hours: open an assist ticket.",
"locales": ["en"],
"tags": ["withdrawal"],
"tools": ["query_transactions", "request_assistance"],
"legacy_ids": []
}
How a code package reads it #
When a turn starts, the platform reads the package's live version and pins it (package, version number, content digest). The whole turn reads only that version. So:
- Saving and publishing change no conversation.
- Once a version is set live, the next turn reads it, in conversations already open too.
- A turn already running does not change.
A code package's main(context, handle) gets that version's content as context.package (PackageContent in packages/ailo-sdk/src/protocol.ts):
| Field | Comes from |
|---|---|
prompt |
The persona's text |
procedure_catalogue |
Each SOP's {name, title, tags}, for listing in the prompt |
faq_catalogue |
Each FAQ entry's {id, title, tags} |
procedures |
SOPs by name; each has title, version, text, tools, tags |
faq |
FAQ entries by name, same fields |
settings |
Site settings; settings.knowledge is true when this version has the knowledge search on |
Desk records the knowledge search. The standard package runs search_faq itself: it takes entries by name from context.package.faq, each cited as faq:<name>@<version>, then calls recordExternal with a record (category: 'knowledge', entries holding only the refs). Only once Desk records it can those refs back a reply; when Desk refuses, the tool answers lookup_rejected.
Today only the built-in standard package runs this way; custom code packages are not open yet. For using the SDK, see Ailo SDK.
import type { Main } from '@ailodesk/ailo-sdk';
export const main: Main = async (context, handle) => {
const sop = context.package.procedures.get('withdrawal-delay');
const faq = context.package.faq.get('withdrawal-time');
// sop?.version and faq?.version are the numbers in the version this turn pinned
// …
return { success: true };
};
const recorded = await scope.recordExternal?.({
requestId: scope.id('lookup'),
name: 'search_faq',
content: body,
record: {
category: 'knowledge',
query: 'withdrawal-time',
call_id: scope.id(),
entries: [{ ref: 'faq:withdrawal-time@4' }],
},
});
if (!recorded?.receipt?.accepted) {
// answer lookup_rejected and keep no citable ref
}
Tool names #
A tool name is the key the three lines share; renaming one changes the interface. The same name appears in three places:
- An SOP's
tools: each name is lower-case letters, digits and_, 1–64 characters, at most 200. - The tool library,
list_agent_tools: where the SOP editor picks names.GET /api/tenants/{tenant_id}/agent-tools[?site_id=…], readable by admins (knowledge.edit); CLIailo tools [--site S]. It returns three groups:builtin(Ailo's own tools, includingread_procedureandsearch_faq),business(business system actions) andmcp(imported MCP tools, namedmcp_<system>_<tool>). Each tool haskind(readorwrite) andsurfaces(whether it is on for Ailo, the workbench and Orbit). - The SDK's
defineTool({ name, … }): a code package's own tools. The SDK does not check the name's format;runAgentrefuses two tools with one name (duplicate_tool).
Names are checked at three points:
- Publish:
check_sopmatches an SOP'stoolsand the tools linked in its text against thelist_agent_toolsnames. - Set live: for each site that runs the package, every tool an SOP needs must exist and be on for Ailo, else
sop_tool_missing; resident tools that no SOP declares must stay within the platform's cap (20 by default). - During a turn: in the built-in loop, an imported MCP tool that an SOP declares appears only after the model has read that SOP; the standard package gets every tool from the start of the turn.
curl "$AILO_BASE_URL/api/tenants/demo-shop/agent-tools" \
-H "Authorization: Bearer $AILO_ACCESS_KEY"
pnpm ailo tools --tenant demo-shop
{
"builtin": [
{ "name": "read_procedure", "kind": "read", "surfaces": { "ailo": true, "desk": false, "orbit": false } }
],
"business": [],
"mcp": [
{ "name": "mcp_shop_order_status", "kind": "read", "surfaces": { "ailo": true, "desk": true, "orbit": false },
"system_id": "shop", "tool": "order_status", "configured": true }
]
}
Still open #
- Tools a code package defines with
defineToolare not inlist_agent_tools. How publish and set live check an SOP that names one is to be confirmed. - Whether content commands will work on code packages once custom code packages open (today they answer
unsupported_package) is to be confirmed.