AI Agent 集成

cz-cli 的重要价值是让 AI Agent 拥有可控、可审计的 ClickZetta 操作入口。你可以在 Claude Code、Cursor、Kiro、Hermes 等工具中，让 Agent 通过命令行调用 cz-cli。

常见自然语言请求

下面示例中的 <profile>、<task_name>、<job_id> 需要替换成你自己的连接配置、任务名和 Job ID。建议让 Agent 先执行 cz-cli -p <profile> status 确认连接可用。

请使用 <profile> 环境，先确认 cz-cli 连接状态，然后列出当前 workspace 中有哪些 schema，再列出 public schema 下的前 20 张表。请使用测试环境 <profile>，帮我在 demo schema 下创建一张订单明细表，插入几行测试数据，然后验证能查到数据。执行写操作前请先给出计划并等待我确认。请使用 <profile> 环境，检查任务 <task_name> 今天是否有失败运行。如果有，请查看运行详情和日志，并给出失败原因与修复建议。请使用 <profile> 环境，分析 SQL job <job_id> 的执行情况，查看 job 状态、结果和执行 profile，判断是否存在性能瓶颈。

通过 cz-cli 自带 Agent 入口执行

如果当前环境已经配置好 cz-cli Agent 所需的大模型参数，也可以直接运行：

cz-cli -p <profile> agent run "帮我检查今天失败的调度任务，并按失败原因分类"

如需给外部 Agent 生成命令说明：

cz-cli ai-guide cz-cli ai-guide --wide cz-cli ai-guide -f json

在企业机器人场景中使用

如果你使用 Hermes 等企业机器人承载 AI Agent，建议将 cz-cli 安装在机器人执行环境中，并采用以下策略：

只给机器人配置必要的 ClickZetta 权限，避免使用高权限管理员账号。
对写入、删除、发布、下线、补数等操作启用人工确认。
对可访问机器人的用户做白名单或审批控制。
将 profile、PAT、密码等凭据放在受控环境变量或本机配置中，不要写入公开文档、聊天记录或代码仓库。

配置 AI Agent 大模型（agent llm）

cz-cli agent run

cz-cli agent run

需要先配置一个大模型才能使用。大模型配置独立于 Lakehouse 连接 profile，存储在

~/.clickzetta/profiles.toml

~/.clickzetta/profiles.toml

的

[llm.*]

[llm.*]

段。

方式一：使用云器内置 LLM（推荐，由 AI Gateway 提供）

云器内置 LLM 通过 AI Gateway 统一提供，无需单独申请模型 API Key。通过 CLI 连接串一步完成配置：

cz-cli setup --credential <CLI连接串>

CLI 连接串在账户控制台的 LakehouseMCP 页面获取（见安装配置指南）。连接串中已包含 AI Gateway 的 Endpoint 和认证信息，配置完成即可使用。

方式二：接入外部 LLM

支持任何 OpenAI 兼容接口。如果企业已有 AI Gateway，直接将其 Endpoint 填入即可：

使用 AI Gateway（企业自建或云器托管）

cz-cli agent llm add my-gateway \ --provider openai-compatible \ --base-url https://<your-instance>.clickzetta.com/gateway/v1 \ --api-key <AI-Gateway-API-Key> \ --use

直接接入 OpenAI / GPT

cz-cli agent llm add my-openai \ --provider openai \ --api-key $OPENAI_API_KEY \ --use

其他 OpenAI 兼容网关

cz-cli agent llm add my-relay \ --provider openai-compatible \ --base-url https://your-gateway.example.com/v1 \ --api-key <API_KEY> \ --use

验证和管理

查看当前激活的 LLM 及所有配置：

cz-cli agent llm show

列出所有已配置的 LLM：

cz-cli agent llm list

测试连通性：

cz-cli agent llm test my-openai

切换使用的 LLM：

cz-cli agent llm use my-openai

删除某个 LLM 配置：

cz-cli agent llm remove my-openai

⚠️ LLM 配置和 Lakehouse 连接 profile 是两套独立配置。

cz-cli setup

cz-cli setup

配置的是 Lakehouse 连接；

cz-cli agent llm add

cz-cli agent llm add

配置的是大模型。两者都需要配置，

cz-cli agent run