AgentScope Runtime 是面向生产环境的智能体（Agent）运行时框架，内置安全工具沙箱、Agent-as-a-Service API、可扩展部署与全栈可观测能力。它的统一命令行入口就叫agentscope——从本地对话调试、Web UI 测试，到一键部署到 K8s / Knative / 阿里云 ModelStudio 等 6 大平台，再到列出、查看、停止已部署的智能体，全部由 9 个子命令完成。本文是一份速查清单，帮你 10 分钟掌握 agentscope 命令行子命令全貌，遇到报错也能快速定位。

一键安装与验证：agentscope CLI 快速上手

先确认 CLI 已安装并可用（源码入口：cli.py）：

pip install agentscope-runtime agentscope --version # 查看版本 agentscope --help # 查看全部子命令

只要--help能列出 9 个子命令，就说明 CLI 工作正常。

agentscope 子命令总览：一张表看懂全部命令

💡 记忆口诀：开发用 chat / web / run，上线用 deploy，运维用 list / status / stop / invoke，沙箱用 sandbox。

开发调试命令速查：chat、web、run 三剑客

agentscope chat：交互式运行与单次查询

chat既可以在开发期直接跑智能体，也可以指向一个部署 ID 测试线上版本（实现见 chat.py）：

agentscope chat app_agent.py # 交互模式，多轮对话 agentscope chat ./my-agent-project # 从项目目录加载 agentscope chat app_agent.py --query "今天天气如何？" # 单次查询后退出 agentscope chat app_agent.py -q "你好" --session-id my-session --user-id u123 agentscope chat ./my-project --entrypoint custom_app.py # 指定目录入口文件

• SOURCE可以是 Python 文件、项目目录，或部署 ID
• --verbose/-v可打印日志和推理过程，排查问题时非常有用

agentscope web：浏览器界面测试

agentscope web app_agent.py # 后端 127.0.0.1:8090，前端 http://localhost:5173/ agentscope web app_agent.py --host 0.0.0.0 --port 8000

注意：首次启动会通过 npm 安装 Web UI 依赖，耗时略长属正常现象（web.py）。

agentscope run：把智能体跑成常驻 HTTP 服务

适合把智能体当后台服务、供其他应用通过 HTTP 调用（run.py）：

agentscope run app_agent.py # 默认 0.0.0.0:8080 agentscope run app_agent.py --host 127.0.0.1 --port 8090 --verbose

服务启动后可通过POST /process端点访问，按 Ctrl+C 停止。

部署命令速查：agentscope deploy 支持哪 6 个平台

deploy是 CLI 中最"重"的命令，一条命令即可把智能体打成部署包并推送到目标平台（deploy.py）：

agentscope deploy <PLATFORM> <SOURCE> [OPTIONS]

6 大部署平台与关键选项对照

K8s 系平台的常用资源选项：--image-name、--image-tag、--registry-url、--push（推送镜像）、--cpu-limit、--memory-limit、--pypi-mirror（pip 镜像源，国内网络建议配置）。

所有平台通用的部署选项

一个典型的生产部署示例：

agentscope deploy k8s app_agent.py \ --image-name my-agent \ --replicas 3 \ --push \ --env DASHSCOPE_API_KEY=sk-xxx

环境变量优先级：-E（CLI）>--env-file>--config。示例配置见 k8s_deploy_config.yaml、modelstudio_deploy_config.yaml。

部署管理命令速查：list、status、stop、invoke

部署完成后，这 4 个命令负责"善后"，都基于部署 ID（形如local_20250101_120000_abc123）：

agentscope list # 列出全部部署 agentscope list --status running # 按状态筛选 agentscope list --platform k8s --format json # 按平台筛选，JSON 输出供脚本处理 agentscope status local_20250101_120000_abc123 # 查看详情（[status.py](https://link.gitcode.com/i/a8a50643bca8d5c8e42a323218b047c5)） agentscope stop local_20250101_120000_abc123 --yes # 停止部署，-y 跳过确认 agentscope invoke local_20250101_120000_abc123 -q "你好" # 调用已部署的智能体

invoke本质是chat <部署ID>的便捷别名（invoke.py），支持--query、--session-id、--user-id。

标准开发到上线工作流（可直接抄）

agentscope chat app_agent.py # 1. 本地调试 agentscope web app_agent.py # 2. Web UI 测试 agentscope deploy local app_agent.py --env DASHSCOPE_API_KEY=sk-xxx # 3. 部署 agentscope list && agentscope status <deployment-id> # 4. 检查状态 agentscope invoke <deployment-id> -q "test" # 5. 验证调用 agentscope stop <deployment-id> # 6. 收尾

沙箱命令速查：agentscope sandbox 的 3 个子命令

沙箱是 AgentScope Runtime 的安全执行环境。统一入口agentscope sandbox下有 3 个子命令（sandbox.py）：

旧的runtime-sandbox-*命令仍然可用，但官方建议迁移到agentscope sandbox *。

高频参数与常见报错速查

高频参数一览

常见报错 60 秒排查

状态文件在哪里？

• 全局部署注册表：~/.agentscope-runtime/deployments.json（自动每日备份，保留 30 天）
• 工作空间构建缓存：当前目录下.agentscope_runtime/builds/，可安全删除以释放空间，建议加入.gitignore

写在最后：这份清单怎么用

把本文当作"贴墙速查表"：开发调试看chat/web/run，上线看deploy六平台对照表，运维看list/status/stop/invoke。完整参数与示例可继续阅读官方文档 cookbook/zh/cli.md；各子命令的源码实现集中在 src/agentscope_runtime/cli/commands/ 目录，遇到怪异行为时可以直接对照源码确认行为细节。