algobot-cli

Algobot 命令行工具

Algolia Agent Studio 是 Algolia 用于构建 AI Agent 的平台，涵盖 RAG 系统、对话体验、生成式 AI 内容生成，并以 Algolia 搜索和推荐作为检索基础。algobot（npm install -g algobot-ai）是用于创建、测试和部署 Agent 的命令行工具。

何时使用 Algobot 与其他工具

需求	使用工具
在 Algolia 上构建／管理 AI Agent（RAG、聊天机器人、生成式 AI 界面）	algobot-cli（本技能）
Algolia 搜索索引操作（记录、设置、同义词）	algolia-cli
搜索查询、分析、推荐	algolia-mcp

设置

npm install -g algobot-ai
algobot init                    # Interactive wizard (creates first agent + profile)

也可以手动添加配置文件（适用于 CI，非交互式）：

algobot profiles add --name prod --env prod

非交互模式（对 Agent 至关重要）

TUI 无法在非 TTY 环境中渲染（CI、脚本、Agent 子进程）。请改用以下命令：

algobot ask "What is your return policy?"                    # One-shot
algobot interactive --text "hello ||| list my orders ||| /context"  # Multi-turn
algobot agents list --jq '.[] | .name'                       # JSON filtering

--jq 已内置，无需单独安装 jq。

核心命令

Agent 管理

algobot agents list
algobot agents get <agent-id>
algobot agents create --name "Support Bot" --model gpt-4o
algobot agents update <agent-id> --name "New Name"
algobot agents publish <agent-id>
algobot agents unpublish <agent-id>
algobot agents delete <agent-id>
algobot agents copy <id> --from-env dev --to-env prod

与 Agent 聊天

algobot ask "Find wireless headphones under $100"
algobot --profile staging ask "hello"        # Target specific environment
algobot --verbose ask "debug this"           # Show full HTTP traces

配置文件／环境管理

algobot profiles list
algobot profiles add --name dev --env dev
algobot profiles setdefault prod
algobot --profile prod agents list
algobot --env dev agents list

配置即代码工作流

使用 mustache 模板对 Agent 定义进行版本控制，非常适合在不同活动、团队或环境中重复部署。

# 1. Scaffold from an existing agent
algobot agents scaffold <agent-id>           # → agent-config.json + PROMPT.md

# 2. Preview (API-level kill switch — mutations blocked by construction)
algobot --dry-run agents create --config agent-config.json --var event="Spring 2026"

# 3. Deploy
algobot agents create --config agent-config.json --var event_name="Spring 2026"

# 4. Update + publish in one step
algobot agents update <id> --config agent-config.json --var event_name="Summer 2026" --publish

JSON 字段中的 {{key}}：使用 JSON 安全转义。.md 指令中的 {{key}}：直接替换。

Agent Studio 功能（通过 Agent 配置）

除了基本聊天，Agent Studio Agent 还支持：

• 工具：Algolia Search、Algolia Browse、Algolia Recommend、客户端工具和 MCP 工具（可将 CRM、库存系统、外部 API 与 Algolia 连接）。使用 algobot tools list/add/remove 管理
• 记忆：跨会话的语义记忆（事实／偏好）和情景记忆（过往交互），通过 algolia_memorize、algolia_ponder 和 algolia_memory_search 工具实现。在 Agent 配置中设置检索模式（预加载或预检）。
• 对话存储：可配置保留期限的持久化历史记录；导出／删除请参阅 algobot conversations
• 实验性功能：响应中的引用标记 [1][2]、日期注入、响应缓存；在 Agent 配置中启用

使用 algobot agents scaffold 检查／编辑这些设置，使用 algobot --dry-run 在应用更改前预览。

实时开发

algobot agents watch patch.json             # Auto-apply patches on file change

Agent Studio 评估

algobot evals 可在终端中运行 Agent Studio Evaluations：指标目录、配置文件快照、数据集生命周期、实验运行、逐案例判定以及前后对比。

版本要求：evals 命令组（以及评估工作流依赖的若干 agents／conversations 修复）要求 algobot-ai >= 2.1.0（npm 最新版）。使用 algobot evals metrics list 探测；如果提示命令未知，则说明已安装的 algobot-ai 版本早于 evals：请停止并安装包含该功能的版本（npm i -g algobot-ai@latest）。

评估与改进工作流详见专用的 agent-studio-evaluations 技能：评估数据集创建（包括真实对话历史导入方法）、结果解读、失败原因到可调参数的映射，以及基于克隆的“改进我的 Agent”调优循环；完整命令列表和评估注意事项见其 references/evaluations.md。对于任何“评估我的 Agent”或 “改进我的 Agent”任务，请加载该技能；本技能仅用于命令行工具相关操作（身份验证、安装、agents/chat/profiles 命令）。

全局标志

标志	效果
--env dev|staging|prod|local	目标环境
--profile <name>	使用命名配置文件
--dry-run	预览但不修改（由 API 强制执行）
--verbose	完整 HTTP 日志
--jq '<expr>'	筛选 JSON 输出
--confirm	跳过 exec 工具确认

注意事项

• TUI 需要 TTY。 不带参数运行 algobot 会启动 TUI，在脚本中会挂起。在非交互环境中，始终使用 ask 或 --text。较新的版本会以退出码 1 拒绝未知子命令，而不是将其默默当作聊天消息（探测：algobot frobnicate 必须以退出码 1 退出；参见上文的版本门控）。在 npm 2.0.0 中，脚本里的拼写错误命令仍可能打印聊天回复并以退出码 0 退出。
• v2.0 中的退出码只有 0/1。 无法区分“未找到”和“身份验证错误”——如有需要，请解析 stderr。
• v2.0 中大多数命令不支持 --output json。 使用 --jq 或 JSON 结构化的 stdout。
• algobot init 是交互式命令。 不要在 CI 中使用——改用带标志的 profiles add。
• prod 会解析到 EU 主机。 v2.0.0 将三个 API 主机硬编码为 agent-studio.eu.algolia.com（生产）、agent-studio-staging.eu.algolia.com（暂存）、conversational-ai-dev.algolia.com（开发）。没有区域标志，且只会读取环境变量 ALGOLIA_APP_ID、ALGOLIA_APPLICATION_ID、ALGOLIA_API_KEY 和 ALGOLIA_AGENT_ID——这些变量都不会覆盖主机。如果某个应用的 Agent 不在 EU，agents list 会返回 []，而 agents get <id> 会对一个实际在线并提供补全服务的 Agent 返回 404。管理员 API 密钥也不会改变这一点。在认定是凭据问题之前，请用 algobot --verbose agents list 确认主机。
• 凭据存储在 ~/.algobot-profiles 中（已加密），而不是 ~/.algobot-cookie。v2.0 已移除 algobot auth show——请使用 algobot profiles list，或使用 algobot profiles show <name> 查看完整详情。请注意，profiles show 会以明文打印 API 密钥，因此请避免在共享终端、屏幕共享和日志中使用。
• --config 会在当前工作目录中自动发现 agent-config.json。 显式指定：--config path/to/config.json。
• algobot 用于开发/部署；REST API 用于生产环境调用。 使用 algobot 构建并发布 Agent；在应用中直接调用 Agent Studio 补全 API。不要猜测端点 URL——运行 algobot agents get <id> 获取，或查看 Agent Studio 控制面板。
• 补全 URL 不带 /agent-studio 前缀。 使用 agent-studio.<region>.algolia.com/1/agents/<id>/completions?stream=false&compatibilityMode=ai-sdk-4。compatibilityMode 为必填项（省略会返回 422）。响应为 { id, role, content }，其中 content 是扁平字符串。

参考文档

• 命令参考 — 每个命令的完整标志说明
• 配置即代码指南 — 模板、变量、多环境模式