HarnessAPI reference

Knowledge and SOP API

Updated 2026-11-12Draft

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.

Save, publish, set live, turn readsSave, publish, set live, turn reads
Saving and publishing change no conversation; only turns that start after set live read the new version
  • 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_version does; 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
Environment
export AILO_BASE_URL=https://api.example.com
export AILO_ACCESS_KEY=<your personal access key>
Command body
{
  "command_id": "4b7e2c1a-9d3f-4e8a-b6c5-0f1e2d3c4b5a",
  "input": { "content_id": "ct_7d2a", "expected_version": 3 }
}
409 response
{ "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. null when 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 truncated is true and you narrow with q.
curl
curl "$AILO_BASE_URL/api/tenants/demo-shop/packages/pkg_demo/content?kind=faq&q=withdraw" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
CLI
pnpm ailo content list pkg_demo --kind faq --q withdraw --tenant demo-shop
200 response
{
  "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
curl "$AILO_BASE_URL/api/tenants/demo-shop/content/ct_7d2a" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
CLI
pnpm ailo content show ct_7d2a --tenant demo-shop
200 response
{
  "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
curl "$AILO_BASE_URL/api/tenants/demo-shop/content/ct_7d2a/versions/3" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
CLI
pnpm ailo content show ct_7d2a --version 3 --tenant demo-shop
200 response
{
  "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 (the documents input 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
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"}}'
CLI
pnpm ailo content import pkg_demo --tenant demo-shop
200 response
{
  "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], where doc.json holds 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
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"}}'
CLI
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
200 response
{ "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
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"]}}'
CLI
pnpm ailo content create pkg_demo --file entry.json --tenant demo-shop
200 response
{ "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 N and ailo 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
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}}'
CLI
pnpm ailo content archive ct_c41e --expected-version 1 --tenant demo-shop
pnpm ailo content restore ct_c41e --tenant demo-shop
200 response
{ "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
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"}}'
CLI
pnpm ailo content publish pkg_demo --tenant demo-shop
200 response
{
  "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
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}}'
CLI
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
200 response
{ "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, answers 404 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
One problem
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
}
check response
{
  "ok": true,
  "version": 2,
  "problems": [
    { "sop": "withdrawal-delay", "field": "tools[0]", "code": "tool_unknown" }
  ]
}
An SOP
{
  "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.

Read an SOP and a FAQ entry
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 };
};
Hand Desk a search record
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:

  1. An SOP's tools: each name is lower-case letters, digits and _, 1–64 characters, at most 200.
  2. 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); CLI ailo tools [--site S]. It returns three groups: builtin (Ailo's own tools, including read_procedure and search_faq), business (business system actions) and mcp (imported MCP tools, named mcp_<system>_<tool>). Each tool has kind (read or write) and surfaces (whether it is on for Ailo, the workbench and Orbit).
  3. The SDK's defineTool({ name, … }): a code package's own tools. The SDK does not check the name's format; runAgent refuses two tools with one name (duplicate_tool).

Names are checked at three points:

  • Publish: check_sop matches an SOP's tools and the tools linked in its text against the list_agent_tools names.
  • 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
curl "$AILO_BASE_URL/api/tenants/demo-shop/agent-tools" \
  -H "Authorization: Bearer $AILO_ACCESS_KEY"
CLI
pnpm ailo tools --tenant demo-shop
200 response (excerpt)
{
  "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 defineTool are not in list_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.