From 962e34a85e063a3b649ad1d6f9aa36f8d7fc84f2 Mon Sep 17 00:00:00 2001 From: Maxime Soufflet Date: Thu, 7 May 2026 10:30:00 +0200 Subject: [PATCH 1/3] docs: agents/providers patch flag is --json, not --file Verified against algobot 2.0.0 (latest): both 'agents patch --help' and 'providers patch --help' show '--json '. There is no --file option. --- skills/algobot-cli/references/commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/algobot-cli/references/commands.md b/skills/algobot-cli/references/commands.md index b2b18f5..a02ba1e 100644 --- a/skills/algobot-cli/references/commands.md +++ b/skills/algobot-cli/references/commands.md @@ -7,7 +7,7 @@ algobot agents list [--jq ''] algobot agents get algobot agents create --name --model [--config ] [--var k=v] algobot agents update [--name ] [--model ] [--config ] [--var k=v] [--publish] -algobot agents patch --file +algobot agents patch --json algobot agents delete algobot agents publish algobot agents unpublish @@ -42,7 +42,7 @@ algobot profiles remove algobot providers list algobot providers get algobot providers create --name -algobot providers patch --file +algobot providers patch --json algobot providers delete ``` From 09aa8f358f14c31072ac17a6fc1557f6cfbb150d Mon Sep 17 00:00:00 2001 From: Maxime Soufflet Date: Thu, 7 May 2026 10:30:10 +0200 Subject: [PATCH 2/3] docs: update agent-config.json shape example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Show the current 'algolia_search_index' tool shape: tools[].name + tools[].indices array of {index, description}. Replaces the placeholder 'tools: [...]' and the stale top-level 'indexName' field. Top-level 'indexName' is silently stripped by the API on submit and does not appear on the stored agent — verified by POSTing a config with both root-level indexName and the new tool shape, then reading back via 'agents get'. --- .../algobot-cli/references/config-as-code.md | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/skills/algobot-cli/references/config-as-code.md b/skills/algobot-cli/references/config-as-code.md index 51c406d..66b6d11 100644 --- a/skills/algobot-cli/references/config-as-code.md +++ b/skills/algobot-cli/references/config-as-code.md @@ -27,15 +27,27 @@ Produces `agent-config.json` with the agent's current config, and `PROMPT.md` if "name": "{{event_name}} Support Bot", "model": "gpt-4o", "instructions": "PROMPT.md", - "tools": [...], - "indexName": "{{index_name}}" + "tools": [ + { + "type": "algolia_search_index", + "name": "search_products", + "indices": [ + { + "index": "{{index_name}}", + "description": "Product catalog. Search by title, brand, or category." + } + ] + } + ] } ``` -- `"instructions": "PROMPT.md"` — loads instructions from the referenced `.md` file -- `{{key}}` — mustache placeholder, resolved via `--var key=value` +- `"instructions": "PROMPT.md"` — loads instructions from the referenced `.md` file. +- `{{key}}` — mustache placeholder, resolved via `--var key=value`. - JSON config fields: JSON-safe escaping. Instructions (`.md`): raw substitution. +> Top-level `indexName` is silently stripped — index names belong in `tools[].indices[].index`. + ## Template Variables ```bash From 74286f9727457e6460272e07a44b3d8e6eae3150 Mon Sep 17 00:00:00 2001 From: Maxime Soufflet Date: Thu, 7 May 2026 10:30:21 +0200 Subject: [PATCH 3/3] docs: add gotchas for completions URL and provider linking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two failure modes that look like 'agent not found' but aren't: 1. The completions URL has no '/agent-studio' path prefix. With the wrong path, the API returns 404 {detail: 'Not Found'} — identical to a missing-agent error. The compatibilityMode query param is also required (omitting it returns 422 ValidationError). Verified against the running prod endpoint. 2. 'agents create --provider ' does not actually link the provider to the agent. The agent stays draft with providerId:null and 'agents publish' 409s with 'Cannot publish without a model or provider.' Workaround verified: 'agents patch --json' with {providerId: } between create and publish. --- skills/algobot-cli/SKILL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/skills/algobot-cli/SKILL.md b/skills/algobot-cli/SKILL.md index 2143700..0a42fc2 100644 --- a/skills/algobot-cli/SKILL.md +++ b/skills/algobot-cli/SKILL.md @@ -145,6 +145,8 @@ algobot agents watch patch.json # Auto-apply patches on file change - **Auth stored in `~/.algobot-cookie`** (AES-256-GCM). Inspect with `algobot auth show`. - **`--config` auto-discovers `agent-config.json`** in cwd. Explicit: `--config path/to/config.json`. - **algobot = dev/deploy tool; REST API = production invocation.** Use algobot to build and publish agents; call the Agent Studio completions API directly from your app. Don't guess the endpoint URL — run `algobot agents get ` to retrieve it, or check the Agent Studio dashboard. +- **Completions URL has no `/agent-studio` prefix.** Use `agent-studio..algolia.com/1/agents//completions?stream=false&compatibilityMode=ai-sdk-4`. `compatibilityMode` is required (omitting → 422). Response: `{ id, role, content }` with `content` as a flat string. +- **`agents create --provider ` does not link the provider.** Agent stays `draft`, publish 409s. After create, run `algobot agents patch --json patch.json` with `{"providerId": ""}`, then publish. ## Reference Docs