@laburen/delta-cli 0.2.0-canary.12 → 0.2.0-canary.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commands/agent-follow-ups/body.d.ts +20 -0
- package/dist/commands/agent-follow-ups/body.js +31 -0
- package/dist/commands/agent-follow-ups/body.js.map +1 -0
- package/dist/commands/agent-follow-ups.d.ts +10 -0
- package/dist/commands/agent-follow-ups.js +129 -0
- package/dist/commands/agent-follow-ups.js.map +1 -0
- package/dist/commands/agent-run/body.d.ts +2 -0
- package/dist/commands/agent-run/body.js +2 -0
- package/dist/commands/agent-run/body.js.map +1 -1
- package/dist/commands/agent-run/render.d.ts +26 -3
- package/dist/commands/agent-run/render.js +47 -6
- package/dist/commands/agent-run/render.js.map +1 -1
- package/dist/commands/agent-run.d.ts +3 -1
- package/dist/commands/agent-run.js +145 -31
- package/dist/commands/agent-run.js.map +1 -1
- package/dist/commands/agent-tools/shared.d.ts +176 -0
- package/dist/commands/agent-tools/shared.js +4 -1
- package/dist/commands/agent-tools/shared.js.map +1 -1
- package/dist/commands/config-sources.d.ts +3 -1
- package/dist/commands/config-sources.js +6 -0
- package/dist/commands/config-sources.js.map +1 -1
- package/dist/commands/config-wizard.js +21 -20
- package/dist/commands/config-wizard.js.map +1 -1
- package/dist/commands/wizards.d.ts +1 -1
- package/dist/commands/wizards.js +9 -1
- package/dist/commands/wizards.js.map +1 -1
- package/dist/errors.d.ts +4 -1
- package/dist/errors.js +558 -44
- package/dist/errors.js.map +1 -1
- package/dist/generated/commands.d.ts +9 -1
- package/dist/generated/commands.js +18 -8
- package/dist/generated/commands.js.map +1 -1
- package/dist/generated/schemas.js +15 -9
- package/dist/generated/schemas.js.map +1 -1
- package/dist/invocation.d.ts +30 -0
- package/dist/invocation.js +130 -33
- package/dist/invocation.js.map +1 -1
- package/dist/operations/file-input.d.ts +5 -0
- package/dist/operations/file-input.js +67 -0
- package/dist/operations/file-input.js.map +1 -0
- package/dist/operations/params.d.ts +3 -1
- package/dist/operations/params.js +35 -6
- package/dist/operations/params.js.map +1 -1
- package/dist/operations/register.d.ts +4 -0
- package/dist/operations/register.js +67 -7
- package/dist/operations/register.js.map +1 -1
- package/dist/operations/run-operation.js +4 -2
- package/dist/operations/run-operation.js.map +1 -1
- package/dist/operations/skeleton.js +13 -5
- package/dist/operations/skeleton.js.map +1 -1
- package/dist/operations/tables.js +11 -2
- package/dist/operations/tables.js.map +1 -1
- package/dist/output.d.ts +2 -0
- package/dist/output.js +30 -5
- package/dist/output.js.map +1 -1
- package/dist/pickers.d.ts +4 -2
- package/dist/pickers.js +29 -15
- package/dist/pickers.js.map +1 -1
- package/dist/program.js +13 -24
- package/dist/program.js.map +1 -1
- package/docs/SKILL.md +22 -14
- package/docs/references/auth-and-organizations.md +2 -0
- package/docs/references/commands.md +188 -20
- package/docs/references/output-and-errors.md +44 -15
- package/package.json +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Commands
|
|
2
2
|
|
|
3
|
-
Every command accepts the global flags `--json`, `--org <id>`, `--api-url <url>`, `--global-config <dir>`, `--non-interactive`, `--no-non-interactive` and `--no-color`; each subcommand's `--help` lists them under "Global Options". `--org ""` fails with `invalid_flag_value`. Commands that create or edit also accept `--data <json|@file|->` with the whole body; individual flags override `--data`. JSON flags take a JSON string or `@file`.
|
|
3
|
+
Every command accepts the global flags `--json`, `--org <id>`, `--api-url <url>`, `--global-config <dir>`, `--non-interactive`, `--no-non-interactive` and `--no-color`; each subcommand's `--help` lists them under "Global Options". `--org ""` fails with `invalid_flag_value`. Commands that create or edit also accept `--data <json|@file|->` with the whole body; individual flags override `--data`. The exception is `agents widgets images upload`, which sends a file: it takes `--file <path>` or `--url <url>` and has no `--data`. JSON flags take a JSON string or `@file`.
|
|
4
4
|
|
|
5
5
|
## Confirmation before deleting
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ If the CLI cannot ask (`--non-interactive`, `--json`, `CI`, or stdin or stderr i
|
|
|
10
10
|
|
|
11
11
|
## Picking a missing id
|
|
12
12
|
|
|
13
|
-
The ids in the commands below are optional, also in `agents tools add` and `agents
|
|
13
|
+
The ids in the commands below are optional, also in `agents tools add`, `agents tools remove`, `agents run` and `agents follow-ups run`. If one is missing and the CLI can ask (a terminal, no `--json`, no `--non-interactive`, no `CI`), it lists the first 100 items and asks you to pick one: the name is the label, the id is shown next to it (an item without a name shows only its id), and the active version is preselected and marked `(current)`. Versions are shown as `v<number> · <date>`. Several missing ids are asked in order: `laburen agents versions activate` asks for the agent and then for the version.
|
|
14
14
|
|
|
15
15
|
- Revoked and expired tokens are left out of the list (and of `choices`). The token of your own CLI session is not marked: the API does not say which one it is. Two items with the same name show the id in the label too (`ci (tok_1)`).
|
|
16
16
|
- In a delete, the active version is still marked `(current)` but the first one that is not active is preselected (the active one cannot be deleted).
|
|
@@ -41,6 +41,7 @@ If the CLI can ask (same rules as above), these `create` commands ask only for w
|
|
|
41
41
|
| | Folder with the skill files (text; read like `--dir`; a folder that cannot be read, is empty or has a binary file is asked again, with the reason on stderr) | `--dir` or `--files` |
|
|
42
42
|
| `mcp connections create` | Connection name (text) | `--name` |
|
|
43
43
|
| | MCP server URL (text) | `--url` |
|
|
44
|
+
| `agents widgets create` | Widget name (text); the look (`--chat-widget`, `--help-page`) is not asked | `--name` |
|
|
44
45
|
|
|
45
46
|
- Answering No to `Configure the first version now?` creates the agent without a version, so it does not ask for skills, MCP connections or activate. Add them later with `laburen agents update <agent_id> --config @config.json` or `laburen agents versions create <agent_id> --config @config.json`.
|
|
46
47
|
- `agents create` with `--skills`, `--mcp-connections` or `--activate` (by flag or in `--data`) and without `--config` fails with `config_required` (exit 2) and nothing is created, because the API would drop them without a version. `next` is your command plus `--config <value>`. If the CLI can ask, it does not fail: it goes straight to the config questions.
|
|
@@ -49,12 +50,12 @@ If the CLI can ask (same rules as above), these `create` commands ask only for w
|
|
|
49
50
|
- Picked skills and connections are sent as `{ "skill_id": ... }` and `{ "connection_id": ... }`. Picking none sends nothing.
|
|
50
51
|
- `mcp connections create` never asks for headers because they are secrets. Pass them with `--headers @headers.json`; in an interactive session stderr reminds you when they are missing (the reminder does not show in non-interactive mode or with `--json`).
|
|
51
52
|
|
|
52
|
-
Ids and values below are placeholders. Run `laburen <command> --help` for the exact flags: it marks the required ones with `(required)` and lists the accepted values (`one of: ...`) when the contract defines them. A required field with only one accepted value shows `(default: <value>)` (for example `--harness-type`, `(default: mastra)`) and is filled in for you. A value outside the accepted list
|
|
53
|
+
Ids and values below are placeholders. Run `laburen <command> --help` for the exact flags: it marks the required ones with `(required)` and lists the accepted values (`one of: ...`) when the contract defines them. A required field with only one accepted value shows `(default: <value>)` (for example `--harness-type`, `(default: mastra)`) and is filled in for you. A value outside the accepted list in a flag fails with `invalid_flag_value` (exit 2) before calling the API, and the message lists the accepted values. A boolean flag together with its `--no-` form (`--ai-enabled --no-ai-enabled`) fails the same way: pass only one. The same value inside `--data` is checked by the CLI in the commands generated from the contract (for example `threads create`), but not in `agents run`: there the API validates it and answers `invalid_request` with the field in `issues`. `--data -` reads the body from stdin; if stdin is a terminal it says so on stderr (end the input with Ctrl-D).
|
|
53
54
|
|
|
54
55
|
## Agents
|
|
55
56
|
|
|
56
57
|
```sh
|
|
57
|
-
laburen agents list # --limit, --after-id, --before-id, --paginate, --search <name>
|
|
58
|
+
laburen agents list # --limit (1 to 100, default 20), --after-id, --before-id, --paginate, --search <name>
|
|
58
59
|
laburen agents get <agent_id>
|
|
59
60
|
laburen agents create --name Support --harness-type mastra
|
|
60
61
|
laburen agents create --data @agent.json # name, harness_type, config...
|
|
@@ -63,15 +64,28 @@ laburen agents update <agent_id> --config @config.json --change-message "new pro
|
|
|
63
64
|
laburen agents delete <agent_id> # needs the admin permission
|
|
64
65
|
```
|
|
65
66
|
|
|
67
|
+
`agents delete` also deletes the threads and the decisions of the agent (the ones with its `agent_id`: its guardrail decisions and the `decisions create` calls charged to it).
|
|
68
|
+
|
|
66
69
|
`agents update` creates a new version only with `--config`, `--skills` or `--mcp-connections`; without them it only edits the name and description, and `--change-message` is not saved (it says so on stderr and goes on). The new version is not activated unless you pass `--activate`; if it stays inactive, stderr says `Created version <n> (not active). Activate it with: ...`, also with `--json` (stdout keeps only the JSON).
|
|
67
70
|
|
|
68
|
-
`agents update --config` **edits**: the new version is the latest one with only the config keys you send replaced. Each top-level key is replaced whole, with no deep merge: `--config '{"knowledge":{"project_ids":[]}}'` drops `knowledge.mode`, so send every field of a key you change. `agents versions create --config` **writes the whole version**: omitted keys are not stored and take their default value on each turn (no `history`:
|
|
71
|
+
`agents update --config` **edits**: the new version is the latest one with only the config keys you send replaced. Each top-level key is replaced whole, with no deep merge: `--config '{"knowledge":{"project_ids":[]}}'` drops `knowledge.mode`, so send every field of a key you change. `agents versions create --config` **writes the whole version**: omitted keys are not stored and take their default value on each turn (no `history`: 12 exchanges without tool calls; no `knowledge`: no knowledge search), so `versions get` does not show them and `compare` shows them as `null`; if a default changes later, a version without that key runs with the new one, there are no skills or MCP connections unless you send `--skills` and `--mcp-connections`, and it never activates (it prints the same notice).
|
|
69
72
|
|
|
70
73
|
```sh
|
|
71
74
|
laburen agents update <agent_id> --config '{"prompt":[{"type":"text","content":"Be brief."}]}' --change-message "shorter answers" # the rest of the config stays
|
|
72
75
|
laburen agents versions create <agent_id> --config @full-config.json --skills '[{"skill_id":"<skill_id>"}]' # everything the version has comes from here
|
|
73
76
|
```
|
|
74
77
|
|
|
78
|
+
`follow_up` is one more top-level key of the config (what the agent writes to a customer who stopped answering: `enabled`, `steps`, `quiet_hours`, `decider`, `reasons`, `instructions`, `model`; only on WhatsApp, Instagram, Chatwoot and CRM). Like the others it is replaced whole, and `--config '{"follow_up":null}'` takes it out. The rules: 1 to 3 `steps`; each `delay_hours` is at least 1 (decimals are fine) and they add up to less than 24 hours; step 1 counts from the last customer message and the next ones from the previous follow-up; `quiet_hours` has hours 0 to 23 in `timezone` (`end` is not included; `start` greater than `end`, like 22 to 6, crosses midnight; `start` equal to `end` means no quiet hours); each item of `reasons` is `{ "id", "category", "description" }` (all three required; `id` unique in the list, `description` up to 500 characters) and lives inside one of 10 categories, which send the follow-up (`open_question`, `cold_lead`, `objection`, `awaiting_confirmation`, `other_send`) or do not (`already_resolved`, `not_interested`, `asked_to_wait`, `conversation_closed`, `other_skip`). Defaults: `enabled` `false`, one step at 3 hours, quiet hours 0 to 6 in `America/Argentina/Cordoba`, `decider` off with `model` `{"id":"gpt_5_mini_openrouter"}` and `share_with_agent` `true`, no `reasons`; without `model`, the follow-up turns use the model of the version. `decider.model` and `model` are objects like `config.model`: `{"id":"<model_id>","reasoning_effort":"low"}` (`reasoning_effort` optional), not a plain id. Edit it with `--config @config.json`: it is too long for a flag. `laburen agents create --skeleton` shows its shape, and to try it without waiting for a customer, see [Follow-ups](#follow-ups).
|
|
79
|
+
|
|
80
|
+
`guardrails` and `attachments` are two more top-level keys of the config. Like the others they are replaced whole, and `--config '{"guardrails":null}'` (or `"attachments":null`) takes them out.
|
|
81
|
+
|
|
82
|
+
- `guardrails` checks every incoming message before the agent runs. `rules` (required, at least one; to turn the guardrail off send `"guardrails": null`, not an empty list) go in order and the first one that fires answers: the agent does not run and the customer gets that rule's `reply`. If the check itself fails, the agent runs normally. Each rule has `name` (1 to 64 letters, digits, `_` or `-`, unique; `language` is reserved), `phase` (only `input`), `question` (`boolean` with `instructions` and optional `criteria.true` / `criteria.false`, or `choice` with `instructions` and `criteria`, option name to its description), `trigger.threshold` (0 to 1: for `boolean`, the probability of yes; for `choice`, the sum of the probabilities of `trigger.choices`, required for `choice`), `model` (`gemini-decision-1`, the default, or `jev-1.14.0`) and `reply` (one text, or language code to text). A rule without `reply` uses `default_reply`; one of the two is required. The model of a rule also sees the attachments of the message that it reads (`gemini-decision-1` images and PDF, `jev-1.14.0` only PNG and JPEG); an attachment it does not read, that does not fit its token limit or, for `jev-1.14.0`, an image with a side outside 280 to 1568 px, is left out (the rule does not see it). The guardrail makes one decision per decision model its rules use (all the rules of that model, plus `language`, go as questions of that one decision), so a turn usually has one decision. Each decision gets as `state` a `json` part `{ "latest_message", "recent_conversation" }` (the message, and the conversation as text, assistant turns included) plus the attachments the model reads. The guardrail adds its own `choice` question `language` (to pick the language of the reply, when the replies have more than one language) and puts two fixed sentences before the `instructions` of each rule (judge only `latest_message` and its attachments; `recent_conversation` is only to understand it). The `guardrail` of each run (`agents run --json`) says which rule fired and has the ids of the decisions of that turn (`decision_ids`): read them with `decisions get`, or list them with `decisions list --thread-id <thread_id>` (see [Decisions](#decisions)).
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
laburen agents update <agent_id> --activate --config '{"guardrails":{"default_reply":"I can only help with questions about the store.","rules":[{"name":"off_topic","phase":"input","question":{"type":"boolean","instructions":"Is the message unrelated to the store?"},"trigger":{"threshold":0.8}}]}}'
|
|
86
|
+
```
|
|
87
|
+
- `attachments` sets how the agent handles files the user sends: `access` (only `inline`), `allow_reread` (default `true`: the model can read an attachment again in later turns), `keep_in_history` (default `false`), `max_tokens_per_attachment` (default 30000) and `max_tokens_per_message` (default 90000).
|
|
88
|
+
|
|
75
89
|
Versions:
|
|
76
90
|
|
|
77
91
|
```sh
|
|
@@ -90,7 +104,7 @@ Without `--json`, `compare` prints one difference per line, with the same rule a
|
|
|
90
104
|
|
|
91
105
|
`--base-version-id <id>` makes the call fail with `409 base_version_mismatch` if that is not the latest version; `--base-version-id null` sends `null` (the resource has no versions yet; on a resource that already has versions it fails with `409 base_version_mismatch`). In a flag that takes a string and not null (`--name null`) `null` is just the text. The only string flag where `null` means "clear" is `tokens update --description null`.
|
|
92
106
|
|
|
93
|
-
`agents get` does not include the config. To read the model, prompt and tools: `laburen agents versions get <agent_id> <active_version_id>` (the active version id is in `agents get`). In a version, reasoning is `config.model.reasoning_effort`; for one run use `agents run --reasoning <level>`. Moving to a model that
|
|
107
|
+
`agents get` does not include the config. To read the model, prompt and tools: `laburen agents versions get <agent_id> <active_version_id>` (the active version id is in `agents get`). In a version, reasoning is `config.model.reasoning_effort`; for one run use `agents run --reasoning <level>`. Moving to a model that reasons (at any level, `off` included) fails if the config has the `thinking` tool. Fix it in one version: read the tools with `agents versions get`, then `laburen agents update <agent_id> --config '{"model":{"id":"<reasoning model>"},"tools":[<all current tools except thinking>]}' --activate` (`tools` replaces the whole list).
|
|
94
108
|
|
|
95
109
|
Tools (reads the latest version, changes `config.tools`, and creates a new version; the new version is not active unless you pass `--activate`):
|
|
96
110
|
|
|
@@ -105,7 +119,15 @@ laburen agents tools remove <agent_id> <tool_id> --change-message "drop thinking
|
|
|
105
119
|
laburen agents tools add --schema # JSON Schema of a tool and of the response; no login, no API call
|
|
106
120
|
```
|
|
107
121
|
|
|
108
|
-
`tools add` and `tools remove` take `--change-message <text>` (stored with the new version). On an agent with no versions `tools add` fails with `agent_has_no_version` (exit 1): there is no config to add the tool to, so create the first version with a config (`next` is `laburen agents versions create <agent_id> --config @config.json`, as you can type it) and then add the tool. `--tool` is required: without it `tools add` fails with `missing_required` and `next` is your command plus `--tool <value>`. `laburen agents tools add --help` shows the tool types and an example `http` tool with `headers`, `body` and `query_parameters` (lists of `{ key, value?, description?, is_user_provided?, required?, accepted_values?, type? }`). `--activate` activates the new version (it sends `activate: true`); without it the version stays inactive and stderr says `Created version <n> (not active). Activate it with: laburen agents versions activate <agent_id> <version_id>`. If the CLI can ask and you passed neither `--activate` nor `--no-activate`, it asks "Activate the new version?" (default No), after the delete confirmation in `tools remove`; `--yes` does not answer it. Without `<agent_id>` both commands pick the agent from `agents list` (see "Picking a missing id"). Without `<tool_id>`, `tools remove` picks from the tools of the latest version (name, or type if it has none, with the id next to it); if it has none it fails with `no_results` and `next` is `tools add`. When the CLI cannot ask, the missing tool fails with `missing_arguments` and `choices` like any other id. A tool or agent picked from a list is always confirmed, even with `--yes`. `tools remove` matches the tool by its `id`. If no tool has it, it fails with `tool_not_found` (exit 1, like any resource that does not exist). Redacted header values (`[REDACTED]`) are sent back as they came; the server keeps the stored secret.
|
|
122
|
+
`tools add` and `tools remove` take `--change-message <text>` (stored with the new version). On an agent with no versions `tools add` fails with `agent_has_no_version` (exit 1): there is no config to add the tool to, so create the first version with a config (`next` is `laburen agents versions create <agent_id> --config @config.json`, as you can type it) and then add the tool. `--tool` is required: without it `tools add` fails with `missing_required` and `next` is your command plus `--tool <value>`. `laburen agents tools add --help` shows the tool types and an example `http` tool with `headers`, `body` and `query_parameters` (lists of `{ key, value?, description?, is_user_provided?, required?, accepted_values?, type? }`). `--activate` activates the new version (it sends `activate: true`); without it the version stays inactive and stderr says `Created version <n> (not active). Activate it with: laburen agents versions activate <agent_id> <version_id>`. `--activate` and `--no-activate` together fail with `invalid_flag_value` (exit 2). If the CLI can ask and you passed neither `--activate` nor `--no-activate`, it asks "Activate the new version?" (default No), after the delete confirmation in `tools remove`; `--yes` does not answer it. Without `<agent_id>` both commands pick the agent from `agents list` (see "Picking a missing id"). Without `<tool_id>`, `tools remove` picks from the tools of the latest version (name, or type if it has none, with the id next to it); if it has none it fails with `no_results` and `next` is `tools add`. When the CLI cannot ask, the missing tool fails with `missing_arguments` and `choices` like any other id. A tool or agent picked from a list is always confirmed, even with `--yes`. `tools remove` matches the tool by its `id`. If no tool has it, it fails with `tool_not_found` (exit 1, like any resource that does not exist). Redacted header values (`[REDACTED]`) are sent back as they came; the server keeps the stored secret.
|
|
123
|
+
|
|
124
|
+
Usage (what an agent cost the organization; needs the `read` permission):
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
laburen agents usage get <agent_id> --from 2026-11-01T00:00:00Z --to 2026-11-30T23:59:59Z
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
It prints `credits_charged`: the credits charged to the organization for the turns of that agent, for the `decisions create` calls charged to it (`--agent-id`) and for its follow-up simulations (`agents follow-ups run`, filter included), between `--from` and `--to` (both included; `--from` after `--to` is a 400 `invalid_request`), `0` when there were none. `--from` and `--to` need date and time with offset (RFC 3339), like `2026-11-18T00:00:00Z` (with `T` between date and time; a space is not accepted): a date alone (`2026-11-18`) fails with `invalid_request` and the message `must be an RFC 3339 date and time, like 2026-11-18T00:00:00Z`. An agent has no balance of its own: credits belong to the organization, and this is what one agent spent of them. It works for any agent of the organization; an agent of another organization, or one that was deleted, is `agent_not_found`.
|
|
109
131
|
|
|
110
132
|
## Run an agent
|
|
111
133
|
|
|
@@ -119,9 +141,11 @@ laburen agents run <agent_id> --version-id <version_id> --context "The user is a
|
|
|
119
141
|
laburen agents run <agent_id> "Hi" --json # waits for the end and prints the final JSON
|
|
120
142
|
```
|
|
121
143
|
|
|
122
|
-
When a delete fails with `resource_in_use`, `details.agent_versions` lists the versions that still assign the skill or MCP connection (or pin one of its versions) as `[{ agent_id, version_id, is_active }]`, without repeats (`details.agent_ids` lists the agents); versions are immutable. The CLI `next` has one command per entry: (1) for `is_active: true`, make the agent stop using the resource: `laburen agents update <agent_id> --skills '[]' --activate` (or `--mcp-connections '[]'`, or the list without that resource); (2) `laburen agents versions delete <agent_id> <version_id>` for each `is_active: false` entry, and also for the version that was active before step 1 (it is inactive now and still assigns the resource; the new active version cannot be deleted); (3) retry the delete. Or delete the agent. Deleting agents, skills
|
|
144
|
+
When a delete fails with `resource_in_use`, `details.agent_versions` lists the versions that still assign the skill or MCP connection (or pin one of its versions) as `[{ agent_id, version_id, is_active }]`, without repeats (`details.agent_ids` lists the agents); versions are immutable. The CLI `next` has one command per entry: (1) for `is_active: true`, make the agent stop using the resource: `laburen agents update <agent_id> --skills '[]' --activate` (or `--mcp-connections '[]'`, or the list without that resource); (2) `laburen agents versions delete <agent_id> <version_id>` for each `is_active: false` entry, and also for the version that was active before step 1 (it is inactive now and still assigns the resource; the new active version cannot be deleted); (3) retry the delete. Or delete the agent. Deleting agents, skills, MCP connections and widgets needs the `admin` permission, and permissions are independent: a token with only `admin` cannot read.
|
|
145
|
+
|
|
146
|
+
Without `<agent_id>` the agent is picked from a list (see [Picking a missing id](#picking-a-missing-id)); the message then comes from `--data`, `--file` or stdin, because a single argument is always the agent id. Without a message, `agents run` fails with `missing_required` (exit 2) before listing anything. With a single argument and no message the error says the argument was read as the agent id, and `next` offers both readings: `laburen agents run <it> <message>` (it is the agent id) and `laburen agents run <agent_id> <it>` (it is the message), plus `laburen agents list`.
|
|
123
147
|
|
|
124
|
-
Runs one turn and shows it live. stdout gets only the text of the answer; reasoning, tool calls and results, sources and the footer go to stderr, so `laburen agents run ... > answer.txt` saves just the answer. The footer has the `thread`, tokens, credits (when the API reports a cost), the duration and the command to continue (`continue: laburen agents run <agent_id> --thread <thread_id> <message>`; put your next message instead of `<message>`). If the agent handed the conversation to a human, the footer says `handed off to a human; the AI is off in this thread`: continuing that thread fails with `ai_disabled_for_conversation
|
|
148
|
+
Runs one turn and shows it live. stdout gets only the text of the answer; reasoning, tool calls and results, sources and the footer go to stderr, so `laburen agents run ... > answer.txt` saves just the answer. The footer has the `thread`, tokens, credits (when the API reports a cost), the duration and the command to continue (`continue: laburen agents run <agent_id> --thread <thread_id> <message>`; put your next message instead of `<message>`). What `continue:` repeats and what it does not is in the notes below. If the agent handed the conversation to a human, the footer says `handed off to a human; the AI is off in this thread`: continuing that thread fails with `ai_disabled_for_conversation` until you turn the AI back on with `laburen threads update <thread_id> --ai-enabled` (not on `chatwoot` or `crm` threads; see [Threads](#threads)). If the input guardrail answered, the footer says `answered by the guardrail rule <name>; the agent did not run (see laburen decisions get <decision_id>)`: the text is the rule's reply. If the turn stopped at the step limit without a final answer, stderr says `Warning: The run stopped at the step limit (max_steps N) before a final answer.` (N is `--max-steps` or the default, 80); the warning does not appear when the turn ended with text.
|
|
125
149
|
|
|
126
150
|
| Flag | Body field | Note |
|
|
127
151
|
|---|---|---|
|
|
@@ -132,8 +156,9 @@ Runs one turn and shows it live. stdout gets only the text of the answer; reason
|
|
|
132
156
|
| `--instructions <text\|@file>` | `instructions` | Replaces the prompt for this run. Needs `write` permission (the API rejects it otherwise) |
|
|
133
157
|
| `--model <id>` | `model` | Same permission |
|
|
134
158
|
| `--reasoning <level>` | `model_settings.reasoning` | `off`, `low`, `medium`, `high` or `max`; same permission. Only for models with reasoning: on a model without it any level, `off` included, fails with `model_settings.reasoning is not allowed`. `laburen models list` shows which models reason and their levels |
|
|
135
|
-
| `--max-steps <n>` | `max_steps` |
|
|
159
|
+
| `--max-steps <n>` | `max_steps` | 1 to 200 (default 80); same permission |
|
|
136
160
|
| `--version-id <version_id>` | `versions.agents[<agent_id>].version_id` | Runs that version instead of the active one; the `continue:` line of the footer repeats it |
|
|
161
|
+
| `--environment evals` | `environment` | Runs with the evals accounts of the model providers and marks the conversation as evals; only `query` permission. The footer says `env evals` and the `continue:` line repeats it. Omit it, or send `null` (`--environment null`, or `"environment": null` in `--data`), for production; it is the same in `threads create` |
|
|
137
162
|
| `--context <text>` (repeatable) | `context[]` | Extra text for the model |
|
|
138
163
|
| `--data <json\|@file\|->` | the whole body | Flags override what `--data` brings; `--file` replaces its `messages` and warns on stderr (`Warning: --file replaces the messages of --data.`) |
|
|
139
164
|
| `--verbose` | | Shows the result of each tool in full instead of cut to one line |
|
|
@@ -158,15 +183,57 @@ laburen agents run <agent_id> --data @run.json --json
|
|
|
158
183
|
Things to know when you run turns:
|
|
159
184
|
|
|
160
185
|
- `contact` is not shown to the model: it only fills in the profile of the contact that `memory.resource` creates. To give the model data about the user, use `--context`.
|
|
161
|
-
- The `continue:` line does not repeat `--resource
|
|
162
|
-
- There is no command to list threads or to read the messages of a conversation: the history is seen in the dashboard. Keep the `memory.thread` of each run if you want to continue it.
|
|
186
|
+
- **What `continue:` repeats.** The global flags you passed (`--org`, `--api-url`, `--global-config`, right after `laburen`; so it also works from a folder without a link), and the flags that change how the turn runs, so that following the thread runs the same thing: `--version-id`, `--environment evals`, `--model`, `--reasoning`, `--instructions` and `--max-steps`. It takes them from the flags or from `--data`, and it repeats them in any environment. With evals this matters: if the model of the agent has no evals route, `--model` is what lets the turn run, and without it the continued turn fails with `evals_not_supported`. `--instructions @file` is repeated as `@file` with the absolute path of the file (so it works from another directory); a text of more than 200 characters or with line breaks is not repeated (the footer is one line), and neither is an `instructions` text from `--data` that starts with `@` (the CLI would read it as a file; there is no way to pass a literal `@`): a line below `continue:` says so (also when the turn is cut by Ctrl+C or fails midway, where the line or the `when` of the `next` carries it), so add `--instructions` again, or use `@file`. A path with spaces is repeated between quotes. It does not repeat `--resource` (the thread already knows its resource, and the server uses it), `--file`, `--context` or the rest of `--data`.
|
|
187
|
+
- There is no command to list threads or to read the messages of a conversation: the history is seen in the dashboard. Keep the `memory.thread` of each run if you want to continue it. To open a thread yourself (with metadata, stored messages or a channel link), see [Threads](#threads).
|
|
163
188
|
- The contacts that `--resource` (or `memory.resource` with `contact` in `--data`) creates cannot be deleted with the CLI.
|
|
164
189
|
- A turn that stopped at `--max-steps` and is continued with `--thread`: by default the agent keeps no tool calls in its history (`config.history.tool_calls.mode` is `off`), so the results of the tools of the cut turn are not in the history and the model may call those tools again. To keep them, set the mode on the agent: `laburen agents update <agent_id> --config '{"history":{"tool_calls":{"mode":"all"}}}' --activate` (or `{"mode":"recent","turns":<n>}`; `exclude_tools` leaves some tools out). `history` is replaced whole, so send `exchanges` and `reasoning` too if you had changed them.
|
|
190
|
+
- `--environment evals` never runs on production. Azure models run as the same model on OpenRouter with the evals account; a model with no evals route fails with its own error code `evals_not_supported` (`details.model`) before anything is created. Evals uses the account of each provider: OpenRouter models, the OpenRouter evals account; Gemini models, the Vertex evals project; Azure models, their pair on OpenRouter with the OpenRouter evals account. A model with no route fails with `evals_not_supported`. Which models have a route is not listed here: `laburen models list` has an EVALS column (`--json`: `capabilities.evals`). With a token that has only `query`, the way out is to run without `--environment`: `models list` needs `read` and `--model` needs `write`. There are no fallback models: one retry of the same model, then the turn fails. Billing is the same as on production. The searches in the knowledge base use the usual accounts. The attachments are read by the model that reads them (the one of the run, or another one that describes or transcribes them: see the `models list` columns below); the tokens of that model are added to `total_usage` and to the cost, so a model that does not read files natively can make a run with a PDF cost much more.
|
|
191
|
+
- An evals conversation only takes evals runs, and a production one only runs without `--environment`; the environment never changes. A mismatch fails with `invalid_request`, `details.reason` `environment_mismatch`, `details.conversation_id` and `details.thread_environment` (`evals` or `null`); the first `next` is the same command with the environment of the thread, and the second is the same command without `--thread` (a new conversation). Neither asks for more permissions than the command you ran (`--model`, `--instructions`, `--reasoning` and `--max-steps` need `write`; without them, only `query`). The `--json` of a run has `environment` (`evals` or `null`), so you can remember it without `continue:`. The `next` that take out `--environment`, `--thread`, `--channel`, `--model` or `--reasoning` take the field out of `--data` too when it is there (`environment`, `memory.thread`, `channel`, `model`, `model_settings.reasoning`); as the `next` shows `--data` as `<value>`, its `when` says which fields to leave out when you send the `--data` again (with a `--data` from a file or stdin, it asks for it just in case).
|
|
192
|
+
- **`guardrail` in the result.** `agents run --json` has `guardrail`: `null` when the agent has no guardrail or it did not run; otherwise `{ "triggered_rule", "decision_ids" }`. `triggered_rule` is the rule that fired (then the agent did not run and `text` is the reply of the rule) or `null`; `decision_ids` are the ids of the decisions the guardrail saved in that turn (one per decision model the rules use; read them with `laburen decisions get <decision_id>`; empty if they could not be saved). If the turn fails after the guardrail ran, its decisions are still saved; in a new conversation the thread was not saved, so they have no `thread_id`: find them with `laburen decisions list --agent-id <agent_id>`.
|
|
193
|
+
- **Fallback models.** In production, when the model of the turn fails, the turn (also the turn of the agent in `agents follow-ups run`) can be answered by a fallback model, and the cost is that of the model that answered. In `agents follow-ups run`, `model` (in `decider` and `agent`) says which model answered. With `--environment evals` there is no fallback (see below).
|
|
194
|
+
- **`model_context_exceeded`** (400, not retryable): the conversation (history, attachments and instructions) does not fit the context window of the model. The `next` is `laburen models list`: pick a model with a larger `context_window`, or start a new conversation without `--thread`. Running the same turn again fails the same way.
|
|
195
|
+
- To simulate the follow-up of an agent, see [Follow-ups](#follow-ups).
|
|
165
196
|
- `--version-id` needs only the `query` permission, also for a version that is not active: that is on purpose (the API contract says so), so a token that can only run agents can try a version before it is activated.
|
|
166
197
|
|
|
167
198
|
The message comes from the argument; if there is none, from `--file` or the `messages` of `--data`; only if none of those exist and stdin is not a terminal is stdin read. In that case the CLI waits at most 500 ms for stdin to start sending: if nothing arrives (an open stdin that sends nothing, as when an AI agent runs the CLI), it does not wait any longer and fails with `missing_required` (exit 2); once data starts, it reads until stdin ends. Pass `-` as the message to read stdin until it ends with no time limit (for a slow command in the pipe); if stdin is a terminal, stderr says `Reading the message from stdin (end with Ctrl-D)...`. `-` together with `--data -` fails with `invalid_flag_value`: there is only one stdin. Without any message it fails with `missing_required` (exit 2).
|
|
168
199
|
|
|
169
|
-
Ctrl+C stops reading and exits with `130`: the turn keeps running on the server and is billed. stderr says so and, if the thread was already known, prints the `continue:` command. If the turn fails midway, what was already printed stays, and the error goes to stderr (exit 1); its `next` is not `--help`. A failed turn may not have been saved, so its thread may not exist: in a new conversation the `next` is the same command again (it starts a new conversation), and only when you passed `--thread` (or `memory.thread` in `--data`) is the `next` the `continue:` command of that thread. If stdout is closed (`| head -1`) the CLI stops quietly and still prints the `continue:` line on stderr; a closed stderr also stops it quietly. A turn that takes more than 10 minutes fails with `turn_deadline_exceeded`.
|
|
200
|
+
Ctrl+C stops reading and exits with `130`: the turn keeps running on the server and is billed. stderr says so and, if the thread was already known, prints the `continue:` command. With `--json` the run is not streamed (it waits for the whole answer), so the CLI does not catch Ctrl+C: the process ends at once with `130` from the shell and prints nothing on stdout or stderr, and the thread is not known. The turn still runs and is billed; the only way to find its conversation is the dashboard. If the turn fails midway, what was already printed stays, and the error goes to stderr (exit 1); its `next` is not `--help`. A failed turn may not have been saved, so its thread may not exist: in a new conversation the `next` is the same command again (it starts a new conversation), and only when you passed `--thread` (or `memory.thread` in `--data`) is the `next` the `continue:` command of that thread. If stdout is closed (`| head -1`) the CLI stops quietly and still prints the `continue:` line on stderr; a closed stderr also stops it quietly. A turn that takes more than 10 minutes fails with `turn_deadline_exceeded`.
|
|
201
|
+
|
|
202
|
+
## Follow-ups
|
|
203
|
+
|
|
204
|
+
```sh
|
|
205
|
+
laburen agents follow-ups run <agent_id> --thread <thread_id> # copies that conversation; query permission
|
|
206
|
+
laburen agents follow-ups run <agent_id> --messages @messages.json --mode decider # only the filter
|
|
207
|
+
laburen agents follow-ups run <agent_id> --thread <thread_id> --step 2 --version-id <version_id>
|
|
208
|
+
laburen agents follow-ups run <agent_id> --messages @messages.json --drafts '{"instructions":"Ask if they are still interested, in one line."}' # write permission
|
|
209
|
+
laburen agents follow-ups run <agent_id> --thread <thread_id> --environment evals
|
|
210
|
+
laburen agents follow-ups run --schema # JSON Schema of the request and the response; no login, no API call
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Simulates the follow-up of an agent (the message it writes to a customer who stopped answering) on a disposable copy of a conversation, and sends nothing to anyone. It is a test: it runs even on a thread with the AI turned off (`ai_enabled: false`), where a normal turn fails with `ai_disabled_for_conversation`. Use it to try `follow_up` (see [Agents](#agents)) before you turn it on. stdout gets the result as a card (the `reason`, `reasoning` and `messages` of the model print with their real line breaks, indented under their field; control characters and terminal sequences are still escaped); with `--json`, the final `FollowUpRun`. It has `outcome` (`would_send`, `skipped` or `failed`), `stopped_by` (`decider`, `agent` or `null`), `decider` (`null` with `--mode agent`), `agent` (`null` with `--mode decider`, or when its turn failed), `cost`, `attempt_id`, `environment` and `error`. `decider` has `decision`, `category`, `child_reason` (the reason of `follow_up.reasons` it chose, or `null`; a reason of another category is dropped and the category stays, also for `agent`; `agent.tool_calls` still shows the arguments the agent sent as they were), `reason`, `confidence`, `reasoning` (when the provider returns it), `model`, `prompt_source` (`draft`, `version` or `default`: which criteria it read) and `cost`. `agent` has `decision`, `declared` (`false` when the agent did not call `decide_follow_up`, the tool it uses to say whether to send; then the follow-up is sent), `category`, `child_reason` and `reason` (what it declared), `messages` (what it would send), `files`, `tool_calls`, `model`, `cost` and `trace_id`. `model` is the name the provider gives to the model (for example `openai/gpt-5-mini`), which can differ from the `id` in `models list`. With `--mode both` the agent writes even when the filter says no: read `outcome` and `stopped_by`, not `agent.messages`.
|
|
214
|
+
|
|
215
|
+
**When the turn of the agent fails.** In `--mode both`, if the filter already decided and then the turn of the agent fails (for example the model provider is down, or `model_context_exceeded`), the run does not fail as a whole: you get the filter's verdict in `decider`, `agent: null`, `outcome: "failed"` (or `"skipped"` if the filter said no) and the error in `error` (`type`, `code`, `message` and `details`, the same shape as an API error, with `details.stage: "agent"`). The command exits with `1`: the card goes to stdout and the error to stderr (with `--json`, stdout carries only the `FollowUpRun`, which already has `error`). `error` is `null` in every other case. That error has no `next` (it is part of the result, not an error of the command): read `error.code` and `error.details.stage`. Any other failure is a normal error (exit 1, no result), and the errors of the filter or of the agent carry `details.stage` (`decider` or `agent`) so you know which part failed; for example, a conversation that does not fit the model of the filter is `model_context_exceeded` with `details.stage: "decider"`.
|
|
216
|
+
|
|
217
|
+
| Flag | Body field | Note |
|
|
218
|
+
|---|---|---|
|
|
219
|
+
| `--thread <id>` | `thread` | A conversation of this agent to copy, from any channel. The original does not change. Send this or `--messages`, only one |
|
|
220
|
+
| `--messages <json\|@file>` | `messages` | A conversation you write, oldest first: `[{"role":"user","parts":[{"type":"text","text":"..."}]},{"role":"assistant","parts":[{"type":"text","text":"..."}]}]`. Text only: a `{"type":"file"}` part is a 400 `invalid_request`, and so is a message whose parts have no text (`details.field` `messages[i]`). The parts of a message are joined with a blank line. `created_at` (RFC 3339) is all or none: every message has it or none does, and the dates cannot go backwards (otherwise a 400 with `details.field` `messages[i].created_at`). Without dates the messages go one after the other and the last one is dated now |
|
|
221
|
+
| `--mode <mode>` | `mode` | `decider` (only the filter), `agent` (skips the filter) or `both` (default). In `both` the agent writes even if the filter says no, and then it does not get the filter's classification. See "The filter" below |
|
|
222
|
+
| `--step <n>` | `step` | Which step of `follow_up.steps` to simulate, 1 to 3 (default 1); its instructions are used |
|
|
223
|
+
| `--version-id <version_id>` | `versions.agents[<agent_id>].version_id` | Runs that version instead of the active one; only `query` permission |
|
|
224
|
+
| `--drafts <json\|@file>` | `drafts` | `{ "instructions"?, "decider_prompt"?, "step_instructions"? }` for this run only, without creating a version. `instructions` and `step_instructions` work together: one replaces the general instructions and the other the ones of the step. Needs the `write` permission, except `--drafts '{}'` |
|
|
225
|
+
| `--environment <evals\|null>` | `environment` | Runs with the evals accounts of the model providers; `null`, or no flag, is production. Only `query` permission |
|
|
226
|
+
| `--data <json\|@file\|->` | the whole body | Flags override what `--data` brings |
|
|
227
|
+
|
|
228
|
+
Things to know:
|
|
229
|
+
|
|
230
|
+
- **The tools run for real.** If a tool creates a booking, the booking is created. Only missing credits stop it, and the run costs credits like a turn (`cost` in the result).
|
|
231
|
+
- **The copy is deleted and the original does not change.** With `agent` and `both` the agent works on a copy of the conversation (the one from `--thread` or the one you wrote) and it is deleted at the end; `decider` needs no copy. The result stays in the attempt (`attempt_id`).
|
|
232
|
+
- You can try a follow-up with `follow_up.enabled` set to `false`, to adjust the prompts before turning it on.
|
|
233
|
+
- **The filter** (`--mode decider` and `both`) runs even when `follow_up.decider.enabled` is off, because this is a test. It uses `follow_up.decider.model` or, without it, `gpt_5_mini_openrouter` (not the model of the agent). `decider_prompt` in `--drafts` replaces the criteria saved in `follow_up.decider.prompt`, and the platform always adds the categories and the output format after it, so the draft sets the criteria, not the shape of the answer. With `--mode agent` the filter does not run and `decider_prompt` is not used.
|
|
234
|
+
- `--environment evals` follows the rules of `agents run` (see [Run an agent](#run-an-agent)). To simulate on a thread without touching production, create the thread with `laburen threads create --environment evals` and pass the same `--environment` here. It never runs on production, and a model with no evals route fails with `evals_not_supported` before the copy is created or anything is charged. Which models are checked depends on `--mode`: `agent` and `both` check the one of the agent (`follow_up.model` or, without it, the `model` of the version); `decider` and `both` check `follow_up.decider.model`. A `--thread` created with the other environment fails with `invalid_request`, `details.reason` `environment_mismatch`.
|
|
235
|
+
- `--thread` and `--messages` together, or neither, fail with `invalid_request`. A `--thread` that does not exist, or belongs to another organization or agent, fails with `conversation_not_found`.
|
|
236
|
+
- The API allows up to 690 seconds for the run; the CLI waits for it and retries with the same `Idempotency-Key`.
|
|
170
237
|
|
|
171
238
|
## Skills
|
|
172
239
|
|
|
@@ -225,11 +292,14 @@ laburen agents widgets create <agent_id> --name "Acme site" --allowed-domains '[
|
|
|
225
292
|
laburen agents widgets list <agent_id> # table: ID, NAME, ENABLED, DOMAINS, ANONYMOUS, UPDATED; newest first
|
|
226
293
|
laburen agents widgets get <agent_id> <widget_id>
|
|
227
294
|
laburen agents widgets update <agent_id> <widget_id> --no-enabled # turn it off; --enabled turns it on
|
|
295
|
+
laburen agents widgets update <agent_id> <widget_id> --chat-widget '{"display_name":"Support","button_color":"#111111"}' --help-page '{"page_title":"Help"}'
|
|
296
|
+
laburen agents widgets images upload <agent_id> <widget_id> logo_light --file ./logo.png # or --url https://...
|
|
297
|
+
laburen agents widgets images delete <agent_id> <widget_id> logo_light
|
|
228
298
|
laburen agents widgets rotate <agent_id> <widget_id> # new identity_secret; the old one stops working
|
|
229
299
|
laburen agents widgets delete <agent_id> <widget_id> # needs admin; the snippet stops working, conversations stay
|
|
230
300
|
```
|
|
231
301
|
|
|
232
|
-
Every response carries the code to install it, with the public token and the URL already set: `web_widget_script` (the `<script>` of the chat bubble: paste it in the site's `<head>` or before `</body>`), `embed_iframe` (an `<iframe>` that shows the chat inside a page, 400×600 by default: change `width`/`height`) and `standalone_url` (a
|
|
302
|
+
Every response carries the code to install it, with the public token and the URL already set: `web_widget_script` (the `<script>` of the chat bubble: paste it in the site's `<head>` or before `</body>`), `embed_iframe` (an `<iframe>` that shows the chat window inside a page, without the button, 400×600 by default: change `width`/`height`) and `standalone_url` (the help page: a full page of its own with the chat, configured by `help_page`; open it to try the widget). Without `--json` the snippet is printed with its line breaks escaped (`\n`), so do not copy it from there: read it with `--json`, for example `laburen agents widgets get <agent_id> <widget_id> --json | jq -r .web_widget_script`. `token` is public (it goes in the snippet).
|
|
233
303
|
|
|
234
304
|
`create` and `rotate` also return `identity_secret`, **only in that response**: without `--json`, stderr says "Save the `identity_secret` now: it will not be shown again." It is what your site's backend uses to sign the visitor's identity token (below); it never goes in the browser. `create` and `rotate` are sent once, never retried (they are not idempotent); `rotate` does not ask for confirmation.
|
|
235
305
|
|
|
@@ -239,12 +309,28 @@ Flags of `create` and `update` (`update` changes only what you pass; `--data` ta
|
|
|
239
309
|
|---|---|---|
|
|
240
310
|
| `--name` | (required in `create`) | Name of the widget, 1 to 100 characters |
|
|
241
311
|
| `--enabled` / `--no-enabled` | on | `--no-enabled` turns it off: the chat answers `widget_not_found`, as if it did not exist |
|
|
242
|
-
| `--allowed-domains` | `[]` | JSON list of sites that can embed it (up to 50); empty = any site. Full host (`www.acme.com` does not include `acme.com`), wildcard only at the start (`*.acme.com` covers subdomains, not `acme.com`), optional port (1 to 65535). A wildcard cannot cover a whole public suffix (`*.com`, `*.com.ar`, `*.co.uk`, `*.github.io`: the list is the Public Suffix List) or an IP. Stored in lowercase, without scheme, path or repeats. `localhost` and its subdomains are rejected: use `127.0.0.1`. An invalid one fails with `invalid_request` on `allowed_domains[i]` |
|
|
312
|
+
| `--allowed-domains` | `[]` | JSON list of sites that can embed it (up to 50); empty = any site. Full host (`www.acme.com` does not include `acme.com`), wildcard only at the start (`*.acme.com` covers subdomains, not `acme.com`), optional port (1 to 65535). A wildcard cannot cover a whole public suffix (`*.com`, `*.com.ar`, `*.co.uk`, `*.github.io`: the list is the Public Suffix List) or an IP. Stored in lowercase, without scheme, path or repeats. `localhost` and its subdomains are rejected: use `127.0.0.1`. An invalid one fails with `invalid_request` on `allowed_domains[i]` and a `details.reason`: `empty_domain`, `invalid_domain`, `localhost_not_supported`, `wildcard_not_at_start`, `wildcard_too_broad` (a wildcard over a top-level domain or a whole public suffix), `wildcard_on_ip` or `invalid_port` |
|
|
243
313
|
| `--allows-anonymous` / `--no-allows-anonymous` | on | `--no-allows-anonymous`: a visitor your site did not identify cannot chat (`identity_required`) |
|
|
244
314
|
| `--max-attachments-per-message` | `5` | Files per visitor message, 1 to 10 |
|
|
245
315
|
| `--visitor-rate-limit` | `null` | JSON `{"max_messages":20,"interval_seconds":60}` (up to 100000 messages and 30 days): cap per visitor; `null` removes it |
|
|
246
316
|
| `--limit-reached-message` | `null` | Text the visitor sees at the cap (1 to 500 characters); `--limit-reached-message null` goes back to the default text |
|
|
247
|
-
| `--
|
|
317
|
+
| `--chat-widget` | `{}` | JSON with the look and behavior of the chat button and the chat window (`web_widget_script` and `embed_iframe`). Fields below |
|
|
318
|
+
| `--help-page` | `{}` | JSON with the look and behavior of the help page (`standalone_url`). Fields below |
|
|
319
|
+
|
|
320
|
+
**Look and behavior: `--chat-widget` and `--help-page`.** In `update`, each field you send replaces that field whole and the fields you do not send stay as they are: `--chat-widget '{"theme":"dark"}'` changes only `theme`. A nested object (`typography`, `accent_color`, `mobile`...) goes complete, with all its fields. To go back to the default, send the default value. The responses always carry every field, with the default for the ones never set. A wrong value fails with `invalid_request` and the field in `issues` (`chat_widget.radius`). `laburen agents widgets update --schema` prints the JSON Schema of every field.
|
|
321
|
+
|
|
322
|
+
Fields of `chat_widget` (default in parentheses):
|
|
323
|
+
- Texts: `display_name` (`null`: the widget name; 1 to 100, not only spaces), `message_placeholder` (`null`: default text; up to 200), `initial_messages` (`[]`: up to 5 agent messages of 1 to 500 characters shown at the start of each conversation; they are not saved nor sent to the model), `dismissable_notice` and `footer` (`null`: HTML up to 500 characters; only bold, italic, underline, `https` links and paragraph alignment are kept; the rest is removed without an error, and a link that is not `https` stays as plain text. The `help_page` buttons are a URL field instead: a link that is not `https` there fails with 400).
|
|
324
|
+
- Suggestions: `suggested_messages` (`[]`: up to 20 quick replies shown while the conversation is empty, each `{"type":"single","text","order","icon"}` or a group `{"type":"nested","name","order","icon","items":[{"text","order","icon"}]}`; `icon` is `null` or one of `message-circle`, `circle-help`, `info`, `shopping-cart`, `calendar`, `phone`, `mail`, `tag`, `truck`, `credit-card`, `user`, `star`), `continue_showing_suggested_messages` (`false`: keep them after each answer).
|
|
325
|
+
- Pop-ups: `auto_open_chat_window_after` (`null`: off; 0 to 600 seconds after the page loads, the initial messages show as pop-ups next to the button, and a click opens the chat), `mobile` (`{"initial_messages":null,"auto_open_chat_window_after":null,"show_auto_open":null}`: what changes under 640 px; each `null` follows desktop). `mobile.initial_messages` is `{"enabled","value"}` with `value` = the list of messages for mobile (up to 5); `mobile.auto_open_chat_window_after` is `{"enabled","value"}` with `value` = the seconds for mobile (0 to 600); in both, `"enabled":false` goes back to the desktop one. `mobile.show_auto_open` is `true` or `false`: whether the pop-ups show on mobile. Example, no pop-ups on mobile: `"mobile":{"initial_messages":null,"auto_open_chat_window_after":null,"show_auto_open":false}` (the object goes complete).
|
|
326
|
+
- Window: `show_attachments` (`true`), `show_dictation` (`true`), `show_copy_button` (`true`), `agent_chat_bubble` (`true`: the agent messages go inside a bubble), `show_profile_picture_border` (`true`).
|
|
327
|
+
- Style: `theme` (`auto`: `light`, `dark` or `auto`, which follows the visitor's system), `accent_color` (`{"enabled":false,"color":"#4CC722"}`), `use_accent_for_header` (`false`), `use_accent_for_send_icon` (`false`), `tinted_grayscale` (`{"enabled":false,"hue":0,"tint":0,"shade":0}`: hue 0 to 360, tint 0 to 9, shade -4 to 4), `radius` (`round`: `sharp`, `soft`, `round` or `pill`), `typography` (`{"font_family":"Inter","font_size":"14px"}`: `Inter`, `System`, `Arial`, `Helvetica`, `Georgia` or `Geist`; `12px` to `20px` in steps of 2).
|
|
328
|
+
- Button: `align_chat_button` (`right`), `button_color` (`null`: default color; `#rrggbb`), `chat_icon` (`laburen`, `chats-filled`, `chat-outline` or `chats-outline`; used when no `launcher_icon` was uploaded), `chat_bubble_text` (`{"enabled":false,"text":"Chat","icon_alignment":"left"}`: text next to the icon, 1 to 30 characters).
|
|
329
|
+
- Read-only: `agent_picture_url` and `launcher_icon_url` (`null` until you upload the image, see Images below). Sending them, or any `*_url` of `help_page` (for example when you send back what `get` returned), fails with `invalid_request` and a message that says it is read-only: drop them from the JSON and change the image with `images upload`.
|
|
330
|
+
|
|
331
|
+
Fields of `help_page` (default in parentheses): `page_title` (`null`: the widget name; 1 to 100, not only spaces), `top_message` (`null`: default welcome; up to 200), `message_placeholder` (`null`; up to 200), `suggested_messages` (`[]`, same shape as in `chat_widget`), `primary_button` and `secondary_button` (`null`: hidden; `{"text","link"}` with text 1 to 50 and an `https` link), `link_buttons` (`[]`: up to 5 more `{"text","link"}`), `theme` (`auto`), `theme_switch_enabled` (`true`: the visitor can switch between light and dark), `primary_color` (`null`: default colors; `{"light":"#rrggbb","dark":"#rrggbb"}`), `show_dictation` (`true`), `show_attachments` (`true`). Read-only: `favicon_url`, `logo_light_url` and `logo_dark_url`.
|
|
332
|
+
|
|
333
|
+
**Images.** `laburen agents widgets images upload <agent_id> <widget_id> <image> --file <path>` uploads one of the five images: `agent_picture` (chat header), `launcher_icon` (chat button), `favicon`, `logo_light` and `logo_dark` (help page). `--url <url>` downloads the file from an `http` or `https` URL and uploads it instead (pass only one of the two). Like the other ids, a missing `<agent_id>`, `<widget_id>` or `<image>` is picked from a list, or fails with `missing_arguments` and `choices` when the CLI cannot ask (for `<image>`, the five names). The file must be PNG or JPG, up to 1 MB. The CLI sends the type of the file extension (`.png`, `.jpg`, `.jpeg`) or, with `--url`, the `content-type` of the download (or the URL extension if the server does not say it). The response is the widget with the new URL in `chat_widget.agent_picture_url`, `chat_widget.launcher_icon_url`, `help_page.favicon_url`, `help_page.logo_light_url` or `help_page.logo_dark_url`. Uploading again replaces the image: the URL changes and the old one stops working (403). `laburen agents widgets images delete <agent_id> <widget_id> <image>` removes it and the field goes back to `null`; removing one that is not there returns the widget unchanged. Both need the `write` permission (not `admin`) and fail with `payment_overdue` while the organization has an overdue payment; `delete` asks for confirmation like any delete. A file that does not work fails with `invalid_request`, `details.field` `file` and the reason in `details.reason`: `too_large` (more than 1 MB), `unsupported_media_type` (the declared type is not PNG or JPG: the extension is not `.png`, `.jpg` or `.jpeg`, or the `--url` download says another type; `details.media_type` is the one that arrived) or `media_type_mismatch` (the declared type is PNG or JPG but the bytes are not: a JPG named `.png`, or a text file named `.png`; `details.declared` and `details.detected`, which is `unknown` when it is neither). Fix the file, not the command. An `<image>` that is not one of the five, a missing file, a failed download or `--file` with `--url` fail with `invalid_flag_value` (exit 2) before calling the API.
|
|
248
334
|
|
|
249
335
|
`allowed_domains` limits who can **embed** the chat (a `Content-Security-Policy: frame-ancestors` header), not who calls the API. Each domain is allowed over `https://`, except `127.0.0.1` and `0.0.0.0`, which use `http://`: a page served over `http` on a public domain (a staging without a certificate) cannot embed the chat.
|
|
250
336
|
|
|
@@ -252,21 +338,97 @@ When changes show: the chat reads the widget on every message, so `--no-enabled`
|
|
|
252
338
|
|
|
253
339
|
The widget answers with the agent's active version. If the agent has none, the widget is created anyway, but every visitor message fails with `invalid_agent_config` ("has no active version") until you activate one (`laburen agents versions activate`).
|
|
254
340
|
|
|
255
|
-
**Identify visitors (optional).** Without it every browser is an anonymous visitor. If the site has its own login, its backend signs an identity token with the `identity_secret` for the logged-in user (for example from an endpoint the page calls with `fetch`), and the page passes it to the widget with `window.$laburen.identify({ token })` (it can run right after the snippet: the snippet queues the call until the widget script loads); the visitor is then linked to a contact of the organization (found or created by `user_id`). The token is a JWT HS256: the key is the UTF-8 bytes of `identity_secret`; `user_id` (non-empty string) and `exp` are required; `email`, `name`, `phone` and `custom_attributes` (an object of strings) are optional. In a Worker or Node backend, `signIdentityToken({ secret, userId, expiresIn? })` from `@laburen/delta-sdk/platform` builds it (see `docs/platform/guide.md` of `@laburen/delta-sdk`, section 14). A bad, expired or incomplete token makes the chat fail with `invalid_identity_token`. The CLI has no command to sign one: signing happens in the site's backend. Other snippet calls: `$laburen.
|
|
341
|
+
**Identify visitors (optional).** Without it every browser is an anonymous visitor. If the site has its own login, its backend signs an identity token with the `identity_secret` for the logged-in user (for example from an endpoint the page calls with `fetch`), and the page passes it to the widget with `window.$laburen.identify({ token })` (it can run right after the snippet: the snippet queues the call until the widget script loads); the visitor is then linked to a contact of the organization (found or created by `user_id`). The token is a JWT HS256: the key is the UTF-8 bytes of `identity_secret`; `user_id` (non-empty string) and `exp` are required; `email`, `name`, `phone` and `custom_attributes` (an object of strings) are optional. In a Worker or Node backend, `signIdentityToken({ secret, userId, expiresIn? })` from `@laburen/delta-sdk/platform` builds it (see `docs/platform/guide.md` of `@laburen/delta-sdk`, section 14). A bad, expired or incomplete token makes the chat fail with `invalid_identity_token`. The CLI has no command to sign one: signing happens in the site's backend. Other snippet calls: `$laburen.open()`, `$laburen.close()` and `$laburen.toggle(open?)` (open or close the chat window), `$laburen.resetChat()` (starts a new conversation, like "New conversation" in the chat menu; the visitor stays the same), `$laburen.reset()` (on logout: forgets the visitor and starts a new anonymous one) and `$laburen.setAttributes(text)` (up to 1000 characters of unverified context sent with the visitor's messages).
|
|
256
342
|
|
|
257
343
|
The CLI and the API do not read or answer the widget's conversations (that is in the dashboard), and the API the chat itself uses in the browser is internal.
|
|
258
344
|
|
|
345
|
+
## Threads
|
|
346
|
+
|
|
347
|
+
A thread is one conversation of an agent. `agents run` creates one for you; `threads` lets you create it first (the response is the thread plus `created` and the stored `messages`; `threads messages create` answers `type: "thread_messages_created"` with its `messages`), with your own data, stored messages, or a link to a customer conversation that already exists in WhatsApp, a CRM or Chatwoot.
|
|
348
|
+
|
|
349
|
+
```sh
|
|
350
|
+
laburen threads create --agent-id <agent_id> --metadata '{"plan":"pro"}' # a thread with metadata
|
|
351
|
+
laburen threads create --agent-id <agent_id> --resource customer-42 \
|
|
352
|
+
--messages '[{"role":"user","parts":[{"type":"text","text":"Hi"}]},{"role":"assistant","parts":[{"type":"text","text":"Hello!"}]}]'
|
|
353
|
+
laburen threads create --agent-id <agent_id> \
|
|
354
|
+
--channel '{"type":"whatsapp","phone_number_id":"<meta phone_number_id>","to":"<wa_id or BSUID>"}'
|
|
355
|
+
laburen threads create --agent-id <agent_id> --environment evals # an evals thread (see Run an agent)
|
|
356
|
+
laburen threads get <thread_id> # read permission
|
|
357
|
+
laburen threads update <thread_id> --metadata '{"plan":"business","vip":null}'
|
|
358
|
+
laburen threads update <thread_id> --ai-enabled # turn the AI back on after a handoff
|
|
359
|
+
laburen threads update <thread_id> --no-ai-enabled # hand the thread to a human
|
|
360
|
+
laburen threads messages create <thread_id> --messages '[{"role":"assistant","parts":[{"type":"text","text":"Your order shipped."}]}]'
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
- **Permissions.** `threads get` needs `read`; `threads create`, `threads update` and `threads messages create` need `write`. `create` and `messages create` answer with ids and roles, not the content of the messages. A thread linked to WhatsApp does not show the number or the `to`, and `resource` is `null` unless you sent it. `threads update` without `--metadata` (or with `{}`) and without `--ai-enabled` / `--no-ai-enabled` changes nothing and returns the thread as it is.
|
|
364
|
+
- **AI on and off.** After the agent hands a conversation to a human (the `request_human` tool), the AI is off and `agents run` on that thread fails with `ai_disabled_for_conversation`. `--ai-enabled` turns it back on (a thread waiting for a human goes back to unresolved); `--no-ai-enabled` turns it off and leaves the thread waiting for a human, like `request_human` but without the email. The thread shows `ai_enabled` (`true` or `false`). Sending the value the thread already has changes nothing. On a `chatwoot` or `crm` thread the AI state is managed in Chatwoot: `ai_enabled` there is `null`, and the flag fails with `invalid_request`, `details.reason` `ai_status_managed_by_channel` and `details.channel`; nothing of the request is saved, not even a `--metadata` sent with it. If a run on one of those threads fails with `ai_disabled_for_conversation`, turn the AI back on by setting the conversation to pending in Chatwoot; the thread picks it up with the next customer message.
|
|
365
|
+
- **Size.** The body of a request is limited to ~1 MB (a bigger one answers 413, without the usual error format): for long histories, send several `threads messages create` batches. The metadata is sent whole in the prompt of every turn: ~600 KB is about 75k input tokens each turn.
|
|
366
|
+
- **History window.** The model sees only the last `config.history.exchanges` exchanges (default 12, max 30): in a longer loaded history the first messages and their files are left out. To raise it, publish a new agent version with a bigger `config.history.exchanges`.
|
|
367
|
+
- **Replies do not go to the channel.** `agents run` on a WhatsApp, CRM or Chatwoot thread does not send the answer through the channel: it comes back only in the API response. The channel delivers when the customer writes.
|
|
368
|
+
- **Messages.** Each one has the shape of the `messages` of `agents run`: `role` is `user` or `assistant` (never `system`) and `parts` are `text` or `file`; a `file` part is accepted only in a `user` message. Validation errors name the field in `issues[].field`: `parts: []` fails on `messages[i].parts`, an empty text on `messages[i]`. Nothing is stored.
|
|
369
|
+
- **Files.** Only `https` urls. They are downloaded and checked when the messages are saved, not when a turn runs: a 404, an `http` url or a `media_type` that does not match the content fails with `invalid_request` and the exact field (`messages[i].parts[j].url` or `.media_type`) in `issues[].field` and `details.field`, and **nothing is stored**: no new thread, no message, no metadata.
|
|
370
|
+
- **Storing messages does not run the agent.** To get an answer, run a turn on that thread: `laburen agents run <agent_id> --thread <thread_id> "<message>"`.
|
|
371
|
+
- **Metadata.** `update` merges by top-level key: the keys you send are set, the others stay, and a key sent as `null` is deleted. A nested object is replaced whole, so a `null` inside it is stored as `null` (it does not delete): `{"a":{"b":null}}` saves `a` as `{"b":null}`. On `create`, a top-level `null` is ignored. The metadata goes to the agent's prompt in every turn, so the model reads it and it costs tokens each time: the key `prompt` is put first as plain text (as JSON if its value is not text), the other keys go as JSON, and `scratchpad` is not shown.
|
|
372
|
+
- **Channel.** `--channel` links the thread to a conversation of a channel, so replies and follow-ups reach the customer. `laburen threads create --help` lists the forms:
|
|
373
|
+
- If the conversation of the channel already exists, `threads create` returns **that** thread (same `id`) instead of creating another: the metadata is merged as in `update` (`null` deletes a key) and the `messages` you send are appended at the end. Parallel calls with the same channel end in one thread. The response has `created`: `true` if this call created the thread, `false` if it found the existing one. **Repeating the call appends the `messages` again** (a template would end up repeated): send them once, or check `created` to decide. Metadata of parallel calls is merged by key; if two write the same key, the last one to reach the server wins. Parallel batches of messages stay contiguous, each in its own order.
|
|
374
|
+
- `whatsapp`: `phone_number_id` is the WhatsApp number of your organization connected to this same agent; `to` is the customer identifier Meta returned when the template was sent (`contacts[0].wa_id`, digits only: no `+` or spaces; or `contacts[0].user_id`, a BSUID in capitals as Meta returns it, like `AR.123456`). If Meta returns both, send the `wa_id`.
|
|
375
|
+
- `crm`: `account_id` and `conversation_id` as the CRM reports them. The agent must have a CRM connected.
|
|
376
|
+
- `chatwoot`: `conversation_id` as Chatwoot reports it.
|
|
377
|
+
- For `crm` and `chatwoot` the conversation must already exist: send the template through the CRM or Chatwoot first, and take the id from there (it is not the contact id).
|
|
378
|
+
- A malformed `--channel` (a missing field, an unknown `type`) is a validation error: `invalid_request` with the field in `issues[].field`. `details.field` is only for business errors (channel, file, empty message). Channel errors:
|
|
379
|
+
- `invalid_request` with `details.reason` `channel_not_connected`: for `whatsapp`, the agent has no WhatsApp number `<phone_number_id>` connected; for `crm` and `chatwoot`, the agent has no CRM or Chatwoot connected. Connect it from the dashboard; the CLI `next` says so (running it again does not fix it).
|
|
380
|
+
- `invalid_request` with `details.reason` `agent_not_linked_to_channel`: the number belongs to another agent, or the existing conversation belongs to another agent. `details.agent_id` is the owner when there is a single one, and the CLI `next` repeats the command with that `--agent-id`.
|
|
381
|
+
- `channel_conversation_not_found` (404): for `crm` and `chatwoot`, that `conversation_id` does not exist in the account (`details.field` is `channel.conversation_id` and `details.channel_conversation_id` is the id you sent). Check the id there; the `next` says creating another thread will not fix it.
|
|
382
|
+
- `channel_provider_unavailable` (529): the CRM did not answer; retry.
|
|
383
|
+
- `conversation_not_found` (404) is only for the thread itself (`threads get/update/messages create`, or `--thread`); the `next` of the `threads` commands is `laburen threads create --agent-id <agent_id>`.
|
|
384
|
+
- `threads create` accepts `--data` or the flags like any other command; `--agent-id` cannot be an agent in conversational mode (`conversational_mode_not_supported`). `agents get` and the version config do not show that mode: it is set in the dashboard, so if you get that error, use another agent.
|
|
385
|
+
- **Resource and contact.** `--resource` on a thread without owner assigns it (in `threads create` with `--channel`, and in `agents run --resource`); a thread that belongs to another resource fails with `thread_resource_mismatch` (403). `contact` without `resource` is ignored, as in `agents run`; the model does not see `contact`.
|
|
386
|
+
- **Evals.** `--environment evals` creates an evals thread: runs on it need `agents run --environment evals`, and the thread shows `"environment": "evals"` (`null` on production). It cannot go with `--channel`, because a channel conversation is a real one: that fails with `invalid_request` and `details.reason` `channel_conversation_is_real`, and the `next` is the same command without `--environment` (or without `--channel`). `--environment` is `evals` or `null`; omit it, or send `null`, for production (the same as in `agents run`, and also `"environment": null` in `--data`). A thread created in evals on an agent whose model has no evals route is created anyway: the check is on each turn, and the turn runs with `--model` (a model with evals) on `agents run --thread <thread> --environment evals --model <id>`. The `--environment` and `--channel` flags are accepted together by the command, but the API rejects the pair.
|
|
387
|
+
- Deleting an agent deletes its threads: afterwards they give `conversation_not_found`.
|
|
388
|
+
|
|
389
|
+
The CLI and the API do not list threads, read their messages or delete them (a thread is deleted only when its agent is deleted), and threads of other channels (a widget, Instagram, MercadoLibre) give `conversation_not_found`.
|
|
390
|
+
|
|
391
|
+
## Decisions
|
|
392
|
+
|
|
393
|
+
`laburen decisions create` asks a decision model one or more questions about a state (text, files and JSON) and answers with one answer per question. It does not run an agent and leaves no trace in the observability tool. The rules (question types, limits, file types of each model) live in the API, not in the CLI.
|
|
394
|
+
|
|
395
|
+
```sh
|
|
396
|
+
laburen decisions create --state '"Hi, I want to cancel my plan"' \
|
|
397
|
+
--questions '{"intent":{"type":"choice","criteria":{"cancel":"Wants to cancel","other":"Something else"},"instructions":"What does the customer want"}}'
|
|
398
|
+
laburen decisions create --model jev-1.14.0 --agent-id <agent_id> --state @state.json --questions @questions.json
|
|
399
|
+
laburen decisions get <decision_id> # read permission
|
|
400
|
+
laburen decisions list --thread-id <thread_id> # read permission; --agent-id, --feature, --limit, --after-id, --before-id, --paginate
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
A `score` question takes `criteria` as a list of levels, from 0 up:
|
|
404
|
+
|
|
405
|
+
```sh
|
|
406
|
+
laburen decisions create --state '"The delivery was late and nobody answered my emails"' \
|
|
407
|
+
--questions '{"anger":{"type":"score","criteria":["Calm","Annoyed","Angry"],"instructions":"How angry is the customer"}}'
|
|
408
|
+
# answers.anger: {"type":"score","score":1.6,...} -> round it: 2, "Angry"
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
- **Values.** `--state` and `--questions` are JSON (`--state` is a JSON string for plain text, or a list of `text`, `file` and `json` parts, `{"type":"json","value":...}`) or `@file`. Up to 10 `file` parts and 20 MB in total; more fails with `invalid_request` (`details.reason` `too_large` when the files add up to more than 20 MB). A `file` part declared as an image, PDF or Office file whose content is an HTML page fails with `invalid_request`, `details.reason` `media_type_mismatch` and `details.detected` `text/html` (the URL points to a web page, not to the file).
|
|
412
|
+
- **Permissions.** `decisions create` needs `query` (the same as `agents run`); `decisions get` and `decisions list` need `read`.
|
|
413
|
+
- **Models.** `gemini-decision-1` (the default) reads images, audio, video and PDF; `jev-1.14.0` reads only `image/png` and `image/jpeg`, and only it supports `box` questions. With `jev-1.14.0` each side of an image must be 280 to 1568 px: otherwise `invalid_request` with `details.reason` `image_out_of_limits`, `details.field`, `details.width` and `details.height`. `--agent-id` charges the cost to that agent (it shows in `agents usage get`). `--environment evals` runs with the evals account of the model provider.
|
|
414
|
+
- **Answers.** One per question, under its key. `boolean` has `probability` (of yes, 0 to 1); `choice` has `choice` (a key of `criteria`); `score` has `score`, the average of the indexes of `criteria` (from 0) weighted by their probability, so it can be fractional (for example `1.6`, between levels 1 and 2): round it to read one level; `box` has `box` (`top`, `bottom`, `left`, `right`), each a fraction of the image from 0 to 1. `choice` and `score` may have `probabilities` (of each option, or of each level keyed by its index); not every model returns them. Any answer can be `{"type":"refusal"}`: the model declined that question, and it is an answer, not an error.
|
|
415
|
+
- **What `create` returns.** A `DecisionCreated`: `id`, `answers`, `model`, `total_usage`, `cost` and `environment`. To see `state`, `questions`, `feature`, `error_code` and the rest, read it with `laburen decisions get <id>`.
|
|
416
|
+
- **Cost.** The answer has `cost`, the credits that call charged. A decision whose model call failed is saved with `error_code` and is not charged; the error carries its id in `details.decision_id` (read it with `decisions get`) and its `next` is `laburen decisions get <decision_id>`. A state that does not fit the decision model fails with `model_context_exceeded`.
|
|
417
|
+
- **`decisions get`.** Reads the decisions of `decisions create` (`decision_api`) and the ones of the input guardrail of an agent (`guardrail_input`). In a guardrail decision `state` holds the message of the end customer (treat it as customer data): a `json` part `{ "latest_message", "recent_conversation" }` and then the attachments the model reads, whose `file` parts have no `url` (see `guardrails` in [Agents](#agents)); the guardrail also evaluates the attachments of the last message, each model only the types it reads. A decision also has `feature` (`decision_api` or `guardrail_input`), `thread_id` and `agent_id` (`null` when none), and `triggered_rule`, `language` and `reply_used`, which have values only in a guardrail decision whose rule fired (`null` when no rule fired, and always in a `decision_api` one). `error_code` is the error code when the model call failed (for example `model_provider_unavailable`), and then `answers` is `null`; it is `null` when the call did not fail. In a guardrail decision a failed call does not stop the agent: the turn runs as if there were no guardrail. `cost` is always `null` in a guardrail decision (the guardrail is charged with the turn).
|
|
418
|
+
- **`decisions list`.** The decisions of the organization, newest first, with the same fields as `decisions get`, paginated like the other lists (`--limit` 1 to 100, default 20; `--after-id`, `--before-id`, `--paginate`). Filters: `--thread-id` (the guardrail decisions of the turns of that thread), `--agent-id` (its guardrail and the `decisions create` calls charged to it) and `--feature` (`decision_api` or `guardrail_input`). They only filter: an `--agent-id` or `--thread-id` that does not exist gives an empty list (unlike `decisions create --agent-id` and `agents usage get`, which answer `agent_not_found`). To find the decisions of one turn, use the `decision_ids` of the `guardrail` of `agents run --json`.
|
|
419
|
+
- **Slow calls.** `create` waits up to 120 s and is retried with the same `Idempotency-Key`. There is no command to delete decisions: the ones with an `agent_id` are deleted with their agent.
|
|
420
|
+
|
|
259
421
|
## Tokens
|
|
260
422
|
|
|
261
423
|
```sh
|
|
262
424
|
laburen tokens list # --search <name>; revoked tokens stay listed
|
|
263
|
-
laburen tokens create --name worker --
|
|
425
|
+
laburen tokens create --name worker --kind personal --permissions '["read"]' # --description, --expires-at, --all-organizations
|
|
264
426
|
laburen tokens update <token_id> --description "worker prod"
|
|
265
427
|
laburen tokens update <token_id> --description null # clears the description
|
|
266
428
|
laburen tokens revoke <token_id>
|
|
267
429
|
```
|
|
268
430
|
|
|
269
|
-
`tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again (`agents widgets create` and `rotate` do the same for `identity_secret`).
|
|
431
|
+
`tokens create` takes `--description` (up to 500 characters), `--expires-at` (RFC 3339; without it the token does not expire) and `--all-organizations` (a personal token for every organization you belong to; then each call needs an organization: see [Which organization is used](auth-and-organizations.md#which-organization-is-used)). It is sent once, never retried (it is not idempotent). `tokens create` prints the token `value` once. Without `--json` it also warns on stderr that the value will not be shown again (`agents widgets create` and `rotate` do the same for `identity_secret`).
|
|
270
432
|
|
|
271
433
|
## Account and organization
|
|
272
434
|
|
|
@@ -277,11 +439,17 @@ laburen whoami # user, organization, credential kind and perm
|
|
|
277
439
|
laburen me get # the same call, raw
|
|
278
440
|
laburen completion [zsh|bash|powershell] # no shell: taken from $SHELL; --install saves it
|
|
279
441
|
laburen orgs list # marks the current one
|
|
280
|
-
laburen models list # table: NAME, ID, REASONING (levels and the default effort), IMAGES (native, described) and PDF (native, text + page image, transcribed), CACHE, CONTEXT, IN $/M, OUT $/M, CACHE READ $/M (all pages; --json also fetches all pages and prints one `{ "data": [ ... ] }`)
|
|
442
|
+
laburen models list # table: NAME, ID, REASONING (levels and the default effort), EVALS (yes if it can run with --environment evals), THINKING TOOL (yes if a version with it can have the thinking tool; the API decides both), IMAGES (native, described) and PDF (native, text + page image, transcribed), CACHE, CONTEXT, IN $/M, OUT $/M, CACHE READ $/M (all pages; --json also fetches all pages and prints one `{ "data": [ ... ] }`)
|
|
281
443
|
laburen orgs switch [<id>] # saves it; without id it asks (in a terminal) or fails with choices
|
|
282
444
|
laburen link --org <id> # writes .laburen/link.json
|
|
283
445
|
laburen unlink # deletes .laburen/link.json
|
|
284
446
|
laburen me organizations list # same data as `orgs list`, raw
|
|
285
447
|
```
|
|
286
448
|
|
|
449
|
+
**What the file columns of `models list` mean** (`--json`: `capabilities`; every model receives images and PDFs, what changes is how). To pick a model, use the capabilities (the provider of a model is not published):
|
|
450
|
+
- `image_input` / IMAGES: `true` / `native` if the model sees the image itself; `false` / `described` (`image_handling: described_as_text`) if another model writes a text description and this one never sees the image.
|
|
451
|
+
- `pdf_input` / PDF: `true` / `native` if the model reads the PDF file itself; otherwise `pdf_handling` is `text_and_image_per_page` (it receives the text of each page plus a JPG of the page) or `transcribed_to_text` (another model transcribes the PDF to markdown and this one receives that text).
|
|
452
|
+
- `prompt_caching` / CACHE: `automatic` if the provider caches the prompt by itself; `explicit` if the cached blocks have to be marked.
|
|
453
|
+
- The tokens of the model that reads, describes or transcribes an attachment are added to `total_usage` and to the cost of the run.
|
|
454
|
+
|
|
287
455
|
See [auth-and-organizations.md](auth-and-organizations.md).
|