Sira AI Command Line Interface

Project description

SiraCLI

Sira AI 命令行工具 - 企业级 AI Agent 平台的 CLI 客户端

安装

pip install siracli

快速开始

1. 配置 API 地址

siracli auth set-url http://localhost:8000

2. 登录

siracli auth login
# 输入邮箱和密码

3. 查看状态

siracli auth status
siracli system health

认证 (auth)

siracli auth login              # 登录
siracli auth logout             # 登出
siracli auth status             # 查看登录状态
siracli auth set-url <url>      # 设置 API 地址

Agent 管理 (agent)

siracli agent list              # 列出所有 Agent
siracli agent get <id>          # 获取 Agent 详情
siracli agent create -n <name> --display-name <display> -m <model-id> -s <system-prompt>  # 创建 Agent
siracli agent update <id>       # 更新 Agent
siracli agent delete <id>       # 删除 Agent

创建 Agent 示例（提示词是必需的）：

siracli agent create \
  -n my_chat_agent \
  --display-name "聊天Agent" \
  -m <MODEL_ID> \
  -s "你是一个有用的AI助手，总是尽力帮助用户解决问题" \
  -d "用于日常对话的AI助手"

Agent 可选参数：

-s, --system-prompt - 系统提示词（必需） - 定义 Agent 的行为和人格
-t, --temperature - 温度参数 (0.0-2.0)
-x, --max-tokens - 最大 token 数
--planning-prompt - 复杂任务的规划提示词
--planning-strategy - 规划策略: none, react, plan_and_execute, reflexion
--enable-memory - 启用对话记忆
--memory-type - 记忆类型: conversation_buffer, conversation_summary 等
--tools - MCP 工具 ID（可多次使用）
--knowledge-bases - 知识库 ID（RAG，可多次使用）
--toolbox-toolsets - GenAI Toolbox 工具集 ID（可多次使用）
--skill - 技能包 ID（仅限 DeepAgents SubAgent 使用，可多次使用）
--streaming - 启用流式响应

关于 skill_ids 参数： --skills 参数用于为 Agent 关联技能包，仅在 DeepAgents 编排器中作为 SubAgent 被引用时生效。当该 Agent 被作为 SubAgent 委托时，其关联的技能包会被加载到 /skills/{subagent_name}/ 目录，供 SubAgent 使用。

Orchestrator 管理 (orchestrator)

siracli orchestrator list               # 列出编排器
siracli orchestrator get <id>           # 获取编排器详情
siracli orchestrator create -n <name> --display-name <display> -t <type>  # 创建编排器
siracli orchestrator delete <id>        # 删除编排器
siracli orchestrator chat <id>          # 与编排器对话(流式)

编排器类型 (--type/-t):

single - 单 Agent 编排
supervisor - 监督者模式
collaboration - 协作模式
workflow - 工作流模式 (复杂，请使用 Web 控制台)
conditional - 条件路由 (复杂，请使用 Web 控制台)
external - 外部服务 (复杂，请使用 Web 控制台)
deep_agents - 深度 Agent (基于 LangGraph 的多智能体协作)
knowledge_base - 知识库编排 (复杂，请使用 Web 控制台)

Deep Agents 编排器 (deep_agents)

Deep Agents 是一种基于 LangGraph 的高级多智能体编排模式，支持 SubAgent 委托、文件系统操作、任务规划等能力。

# 创建 Deep Agents 编排器
siracli orchestrator create \
  -n my_deep_agent \
  --display-name "我的深度智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  [--subagent-model-id <SUBAGENT_MODEL_ID>] \
  [--subagent <AGENT_ID>] \
  [--skill <SKILL_ID>] \
  [--tool <TOOL_ID>] \
  [--system-prompt <PROMPT>] \
  [--backend-type <state|store|filesystem|local_shell>] \
  [--backend-path <PATH>] \
  [--recursion-limit 25] \
  [--enable-checkpoint | --disable-checkpoint]

必需参数：

-n, --name - 编排器名称（唯一标识）
-D, --display-name - 显示名称
-t, --type - 编排类型，设为 deep_agents
--ai-model-id - 主 LLM 模型 ID（必填）
--system-prompt - 系统提示词（必填）

可选参数：

参数	说明	默认值
`--subagent-model-id`	SubAgent 默认模型 ID	使用 `--ai-model-id`
`--subagent`	SubAgent 的 Agent ID（可多次使用添加多个）	无
`--skill`	技能包 ID（可多次使用添加多个）	无
`--tool`	MCP 工具 ID（可多次使用添加多个）	无
`--system-prompt`	主 Agent 系统提示词	默认研究助手提示词
`--backend-type`	Backend 存储类型	`state`
`--backend-path`	文件系统后端路径（backend-type=filesystem 时使用）	`/tmp/deep_agents`
`--recursion-limit`	LangGraph 递归限制	`25`
`--enable-checkpoint`	启用检查点（保存会话状态）	启用
`--timeout`	执行超时时间（秒）	`120`
`--enabled`	创建后启用编排器	启用

Backend 类型：

state - 内存存储（适合小文件，默认）
store - 持久化存储（Redis/PostgreSQL）
filesystem - 文件系统存储（适合大文件）
local_shell - 本地 shell 执行（仅开发环境）
sandrpod - SandrPod 远程沙箱（需额外配置 Server URL 和 Sandbox 名称）

SandrPod Backend 可选参数：

参数	说明	默认值
`--backend-api-url`	SandrPod Server URL	`http://localhost:8080`
`--backend-sandbox`	Sandbox 名称	`default`
`--backend-timeout`	执行超时时间（秒）	`60`
`--backend-use-session`	是否使用 Session 模式保持状态	`true`

使用 SandrPod Backend 示例：

siracli orchestrator create \
  -n sandbox_agent \
  --display-name "沙箱智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个研究助手..." \
  --backend-type sandrpod \
  --backend-api-url http://localhost:8080 \
  --backend-sandbox my-sandbox

SubAgent 格式：

直接指定 Agent ID：--subagent <AGENT_ID>
预定义类型：--subagent predefined:research-agent

创建示例：

# 最简创建（使用相同模型）
siracli orchestrator create \
  -n my_deep_agent \
  --display-name "我的深度智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个AI助手..."

# 带技能包和工具
siracli orchestrator create \
  -n research_assistant \
  --display-name "研究助手" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个研究助手..." \
  --skill <SKILL_ID_1> \
  --skill <SKILL_ID_2> \
  --tool <TOOL_ID>

# 带 SubAgent
siracli orchestrator create \
  -n multi_agent \
  --display-name "多智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个多智能体助手..." \
  --subagent <AGENT_ID_1> \
  --subagent <AGENT_ID_2>

# 使用文件系统后端
siracli orchestrator create \
  -n file_agent \
  --display-name "文件智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个文件处理助手..." \
  --backend-type filesystem \
  --backend-path /tmp/my_deep_agents

# 使用 SandrPod 远程沙箱后端
siracli orchestrator create \
  -n sandbox_agent \
  --display-name "沙箱智能体" \
  -t deep_agents \
  --ai-model-id <MODEL_ID> \
  --system-prompt "你是一个沙箱执行助手..." \
  --backend-type sandrpod \
  --backend-api-url http://localhost:8080 \
  --backend-sandbox my-sandbox

更新 Deep Agents 编排器：

siracli orchestrator update <ORCHESTRATOR_ID> \
  [--ai-model-id <MODEL_ID>] \
  [--subagent-model-id <MODEL_ID>] \
  [--subagent <AGENT_ID>] \
  [--skill <SKILL_ID>] \
  [--tool <TOOL_ID>] \
  [--backend-type <TYPE>] \
  [--recursion-limit <N>] \
  [--enable-checkpoint | --disable-checkpoint]

查看编排器详情：

siracli orchestrator get <ORCHESTRATOR_ID>

输出示例：

============================================================
Orchestrator Details
============================================================
ID                   xxx-xxx-xxx
Name                 my_deep_agent
Display Name         我的深度智能体
Type                 deep_agents
Status               ● Active
Created At           2026-03-30T00:00:00

Deep Agents Config:
  AI Model ID: xxx
  SubAgent Default Model: xxx
  SubAgents (2):
    - agent_ref: xxx-xxx
    - agent_ref: xxx-yyy
  Tool IDs (1):
    - xxx-zzz
  Skill IDs (1):
    - xxx-skill
  Backend Type: state
  Recursion Limit: 25
  Checkpoint: Enabled

AI 模型管理 (model)

siracli model list               # 列出 AI 模型
siracli model get <id>           # 获取模型详情
siracli model create -n <name> -p <provider> -m <model-name>  # 创建模型配置
siracli model update <id>        # 更新模型配置
siracli model delete <id>       # 删除模型配置
siracli model test <id>          # 测试模型连接

模型提供商 (--provider/-p):

openai, claude, deepseek, qwen
azure_openai, local, custom

应用管理 (application)

siracli application list                  # 列出应用
siracli application get <id>              # 获取应用详情
siracli application create -n <name> --display-name <display> -p <platform> -o <orchestrator-id>  # 创建应用
siracli application update <id>           # 更新应用
siracli application delete <id>           # 删除应用
siracli application info <id>             # 获取应用连接信息
siracli application chat <id> -m <msg>    # 与应用对话(流式)

应用平台类型 (--platform/-p):

webclient - Web 客户端
api_service - API 服务

聊天模式

Web 类型应用（需要登录）:

siracli application chat <app_id> -m "你好"

API 类型应用（使用 API Key）:

siracli application chat <app_id> -m "你好" -k <api_key>

API Key 管理 (apikey)

siracli application apikey list -a <app_id>           # 列出应用的 API Key
siracli application apikey get <key_id>               # 获取 API Key 详情
siracli application apikey create -a <app_id> -n <name>  # 创建 API Key
siracli application apikey update <key_id>            # 更新 API Key
siracli application apikey delete <key_id>            # 删除 API Key
siracli application apikey test <key_id>               # 测试 API Key

MCP 工具 (mcp)

siracli mcp list-tools             # 列出 MCP 工具
siracli mcp list-services          # 列出 MCP 服务
siracli mcp info <id>              # 获取 MCP 工具/服务详情
siracli mcp test <id>              # 测试 MCP 工具连接
siracli mcp create -n <name> -t <type>  # 创建 MCP 工具
siracli mcp delete <id>            # 删除 MCP 工具

MCP 工具类型 (--type/-t):

registry - 注册表类型（从远程注册表加载）
manual - 手动类型（本地命令行）
builtin - 内置类型
service - 服务类型（HTTP 接口）

服务类型 MCP 工具参数:

--protocol/-p - 协议类型: sse, streamable-http, stdio
--service-url/-u - 服务 URL

人工审批 (HITL × Card)

LangGraph Human-in-the-Loop 与跨 channel 卡片审批。三层配置叠加，所有层都通过 CLI 暴露。详见 devdocs/HITL_INTERACTIVE_CARD_DESIGN.md。

Layer 1: MCP 工具自身（兜底默认）

工具作者标记某个工具默认要审批：

# 创建时
siracli mcp create -n delete_db -t service \
  --protocol streamable-http --service-url https://… \
  --requires-approval \
  --approval-decisions approve,reject \
  --approval-description "AI 想清空数据库 {args.target}"

# 后期开关
siracli mcp update <tool-id> --requires-approval
siracli mcp update <tool-id> --no-requires-approval
siracli mcp update <tool-id> --approval-decisions approve,reject,edit
siracli mcp update <tool-id> --approval-description "确认执行 {tool_name}"

# 查看
siracli mcp info <tool-id>     # 末尾会列 HITL Approval 区块

Service 类型工具的 per-tool 白/黑名单

一个 MCP service 通常含 N 个工具（如 tavily-mcp 含 search / extract / crawl / map ...）。如果对整个 service 勾"需要审批"，所有工具都会拦——多数场景太粗。--hitl-mode + --hitl-tool 让你按工具名细化：

# 白名单：只对 tavily_crawl 拦（爬整站较激进），其它默认放行
siracli mcp create -n tavily -t service \
  --protocol streamable-http --service-url https://… \
  --requires-approval \
  --hitl-mode whitelist \
  --hitl-tool tavily_crawl

# 黑名单：默认全审，但 tavily_search 调用频繁不想被打扰
siracli mcp update <tool-id> \
  --hitl-mode blacklist \
  --hitl-tool tavily_search \
  --hitl-tool tavily_extract

# 退回到全审（删除 per-tool 配置）
siracli mcp update <tool-id> --clear-hitl-per-tool

# update 时只换工具列表（mode 保持原样）
siracli mcp update <tool-id> --hitl-tool new_tool_a --hitl-tool new_tool_b

仅对 service 类型 MCP 有意义；stdio 单工具直接用 --requires-approval 就够了。配置存在 configMetadata.hitl_per_tool。

Layer 2: Orchestrator（编排器）

按业务场景给工具加白/黑名单，或一键静默整编排器。single / supervisor / collaboration / deep_agents 任一类型都生效——后端从 deep_agents_config JSONB 列读取，不区分 orchestration_type。

# DeepAgents（含 ai_model / system_prompt 等其他字段一起创建）
siracli orchestrator create -n my_orch -D 客服 -t deep_agents \
  --ai-model-id <id> -s "You are…" \
  --interrupt-on send_email \
  --interrupt-on execute \
  --interrupt-off ls            # 显式关掉某个 tool 默认 requires_approval

# Single 编排器（最常见的"一个 Agent + 工具"模式也可以挂 HITL）
siracli orchestrator create -n simple_bot -D 简单助手 -t single \
  --agent-id <agent_id> \
  --interrupt-on delete_db      # 调 delete_db 前弹卡片

# 整编排器静默（开发/调试 / 批量 cron 等场景）
siracli orchestrator update <orch-id> --hitl-disabled
siracli orchestrator update <orch-id> --no-hitl-disabled

# 增量加 / 减规则（与 existing.interrupt_on 合并，不覆盖其它字段）
siracli orchestrator update <orch-id> --interrupt-on transfer_money
siracli orchestrator update <orch-id> --interrupt-off send_email

# 脚本化批量配（完整 dict）
siracli orchestrator update <orch-id> --interrupt-on-json '{
  "delete_db": true,
  "execute": {"allowed_decisions": ["approve","reject"]},
  "send_email": false
}'

# 清空编排器层规则
siracli orchestrator update <orch-id> --clear-interrupt-on

# 查看（任意 orchestration_type 都会显示 HITL 区块）
siracli orchestrator get <orch-id>

Layer 3: Application（应用，最高优先级）

部署级覆盖：同一编排器在不同 application 走不同策略。

# 创建时
siracli application create -n my_app -D Bot -p api_service \
  -o <orchestrator-id> \
  --hitl-disabled \                            # 整应用静默（OR-merge 编排器层）
  --interrupt-override delete_db \             # 强制开启某个工具审批
  --interrupt-override-off send_email          # 强制关闭某个工具审批

# 后期切换
siracli application update <app-id> --hitl-disabled
siracli application update <app-id> --no-hitl-disabled
siracli application update <app-id> --interrupt-override transfer_money
siracli application update <app-id> --interrupt-override-off ls
siracli application update <app-id> --interrupt-overrides-json \
  '{"delete_db": {"allowed_decisions": ["approve"]}}'
siracli application update <app-id> --clear-interrupt-overrides

# 查看
siracli application info <app-id>   # 末尾会显示 HITL (application layer) 区块

合并语义速记

Layer	字段	合并行为
1 (MCP 工具)	`requires_approval` + `approval_decisions` + `approval_description`	兜底默认
2 (编排器)	`hitl_disabled` (bool) + `interrupt_on` (per-tool)	覆盖 layer 1
3 (应用)	`hitl_disabled` (bool) + `interrupt_overrides` (per-tool)	覆盖 layer 1+2

hitl_disabled 是 OR 合并：编排器或应用任一勾选都静默。 "管理员强制开启被静默的编排器" 是另一个尚未实现的字段 (hitl_required，V2 计划)。

知识库 (kb)

siracli kb list              # 列出知识库
siracli kb info <id>         # 获取知识库详情

GenAI Toolbox (toolbox)

siracli toolbox list              # 列出工具集
siracli toolbox info <id>         # 获取工具集详情

Skill 管理 (skill)

# 列表和搜索
siracli skill list                              # 列出所有 Skills
siracli skill search <keyword>                    # 搜索 Skills
siracli skill search weather --status published   # 按状态筛选
siracli skill info <id>                          # 获取 Skill 详情

# 创建和更新
siracli skill create -n <name> -f <file.md>    # 从文件创建
siracli skill create -n <name> -f ./skill-dir/  # 从目录创建
siracli skill update <id> -n <name>             # 更新元数据
siracli skill update <id> -f <file.md>          # 更新单文件
siracli skill import-into <id> <file.zip>       # 导入到现有 Skill

# 导入导出
siracli skill import-url <url>                   # 从 URL 导入
siracli skill import-file <file.zip>             # 导入为新 Skill
siracli skill export <id> -o <output.zip>       # 导出为 ZIP

# 安装到本地
siracli skill install <id>                      # 安装到本地 Claude
siracli skill install <id> -p claude            # 指定平台
siracli skill install <id> -d ./my-skills/      # 自定义目录

# 版本控制
siracli skill versions <id>                    # 查看版本历史
siracli skill restore <id> <version>           # 恢复到指定版本

# 删除
siracli skill delete <id>                       # 删除 Skill（软删除）

安装自动检测逻辑：

当前目录有 .claude 文件夹 → 安装到 $(pwd)/.claude/skills/
当前目录有 openclaw.json → 安装到 ~/.openclaw/skills/
否则 → 安装到 ~/.claude/skills/

系统 (system)

siracli system health            # 健康检查
siracli system stats             # 系统统计
siracli system info              # CLI 和 API 信息
siracli system version           # 版本信息

配置

配置文件存储在 ~/.siracli/token.json

{
    "api_url": "http://localhost:8000",
    "token": "your-session-token",
    "user": {
        "id": "...",
        "name": "...",
        "email": "..."
    }
}

完整示例：从创建到调用 API

以下示例展示如何通过 CLI 创建 Agent、编排器、应用、API Key，并使用 API Key 调用。

第一步：查看可用资源

# 查看可用的 AI 模型
siracli model list

# 查看可用的 MCP 工具（可选）
siracli mcp list-tools

第二步：创建 Agent

Agent 是实际执行任务的单元，需要绑定模型和提示词。

# 查看现有 Agent
siracli agent list

# 创建新 Agent（MODEL_ID 从 model list 获取）
siracli agent create \
  -n my_chat_agent \
  --display-name "聊天Agent" \
  -m <MODEL_ID> \
  -s "你是一个有用的AI助手，总是尽力帮助用户解决问题" \
  --description "用于聊天的Agent"

重要：-s/--system-prompt 是创建 Agent 的必需参数，定义 Agent 的行为和人格。

第三步：创建编排器

编排器负责任务编排，single 类型表示单 Agent 编排。

# 创建单 Agent 编排器（需要指定 agent-id）
siracli orchestrator create \
  -n my_orchestrator \
  --display-name "我的编排器" \
  -t single \
  --agent-id <AGENT_ID> \
  --description "简单的单Agent编排"

第四步：创建应用

应用是对外暴露的接口，API 类型支持 API Key 调用。

# 创建 API 类型应用
siracli application create \
  -n my_api_app \
  --display-name "我的API应用" \
  -p api_service \
  -o <ORCHESTRATOR_ID>

第五步：创建 API Key

# 为应用创建 API Key
siracli application apikey create \
  -a <APPLICATION_ID> \
  -n test_key

重要：创建成功后返回的 API Key（api_sk_xxx）只会显示一次，请妥善保存！

第六步：使用 API Key 调用

# 使用 API Key 调用应用（OpenAI 兼容接口）
siracli application chat <APPLICATION_ID> \
  -m "你好，请介绍一下你自己" \
  -k <API_KEY>

API 调用地址

API 端点地址为：{API_URL}/v1/chat/completions

# 查看当前配置的 API 地址
siracli auth status

# 直接用 curl 调用
curl -X POST "{API_URL}/v1/chat/completions" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<APPLICATION_ID>",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": false
  }'

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行
python -m siracli.cli --help

Project details

Release history Release notifications | RSS feed

2.4.4

Jun 29, 2026

2.4.3

Jun 28, 2026

2.4.2

Jun 28, 2026

2.4.1

Jun 27, 2026

2.4.0

Jun 24, 2026

This version

2.3.0

May 29, 2026

2.2.0

May 5, 2026

2.1.0

May 2, 2026

2.0.0

Apr 30, 2026

0.1.2

Mar 30, 2026

0.1.1

Mar 30, 2026

0.1.0

Mar 30, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

siracli-2.3.0.tar.gz (67.0 kB view details)

Uploaded May 29, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

siracli-2.3.0-py3-none-any.whl (70.2 kB view details)

Uploaded May 29, 2026 Python 3

File details

Details for the file siracli-2.3.0.tar.gz.

File metadata

Download URL: siracli-2.3.0.tar.gz
Upload date: May 29, 2026
Size: 67.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.14

File hashes

Hashes for siracli-2.3.0.tar.gz
Algorithm	Hash digest
SHA256	`0cbcf1ef091b271a543a78ff32c923ae70ce62284a02f519e4afa710fa8593f3`
MD5	`bce94a4a3132cb38405396b041b27d5b`
BLAKE2b-256	`f723d43f6c2f9097bd9151eb4a2047eec144eef1a8d2f8fbdc9586245e5be116`

See more details on using hashes here.

File details

Details for the file siracli-2.3.0-py3-none-any.whl.

File metadata

Download URL: siracli-2.3.0-py3-none-any.whl
Upload date: May 29, 2026
Size: 70.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.14

File hashes

Hashes for siracli-2.3.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`bf6fb6c37e4fb03fe3c37dd27b38fecc428b142084d10d19a680b5af41f1cd35`
MD5	`5ff27b5ca31f2ab44a3856353026fa02`
BLAKE2b-256	`2ecae0efd9d8cfceb1556851affe4082b91cdfc29c44dfbb1f4d878fb6625ab2`

See more details on using hashes here.

siracli 2.3.0

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

SiraCLI

安装

快速开始

1. 配置 API 地址

2. 登录

3. 查看状态

认证 (auth)

Agent 管理 (agent)

Orchestrator 管理 (orchestrator)

Deep Agents 编排器 (deep_agents)

AI 模型管理 (model)

应用管理 (application)

聊天模式

API Key 管理 (apikey)

MCP 工具 (mcp)

人工审批 (HITL × Card)

Layer 1: MCP 工具自身（兜底默认）

Service 类型工具的 per-tool 白/黑名单

Layer 2: Orchestrator（编排器）

Layer 3: Application（应用，最高优先级）

合并语义速记

知识库 (kb)

GenAI Toolbox (toolbox)

Skill 管理 (skill)

系统 (system)

配置

完整示例：从创建到调用 API

第一步：查看可用资源

第二步：创建 Agent

第三步：创建编排器

第四步：创建应用

第五步：创建 API Key

第六步：使用 API Key 调用

API 调用地址

开发

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes