cargo-ai

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CLI — AI

Agent resource management: creating and configuring agents, uploading files for retrieval-augmented generation (RAG), connecting MCP servers, and managing agent memories.

For using agents (sending messages, multi-turn chat, polling), use
cargo-orchestration
. For workspace administration — folders (used to organize agents and files), users, API tokens, roles, and submitting reports when the CLI fails — use
cargo-workspace-management
.

See
references/response-shapes.md
for full JSON response structures. See
references/troubleshooting.md
for common errors and how to fix them. See
references/examples/agents.md
for agent CRUD and configuration examples. See
references/examples/files.md
for file upload and management examples. See
references/examples/mcp-servers.md
for MCP server creation and management examples.

Agent资源管理：创建和配置Agent、上传用于检索增强生成（RAG）的文件、连接MCP服务器以及管理Agent记忆。

若要使用Agent（发送消息、多轮对话、轮询），请使用
cargo-orchestration
。若要进行工作区管理——文件夹（用于组织Agent和文件）、用户、API令牌、角色，以及在CLI故障时提交报告，请使用
cargo-workspace-management
。

完整JSON响应结构请查看
references/response-shapes.md
。常见错误及修复方法请查看
references/troubleshooting.md
。 Agent的增删改查（CRUD）和配置示例请查看
references/examples/agents.md
。文件上传和管理示例请查看
references/examples/files.md
。 MCP服务器创建和管理示例请查看
references/examples/mcp-servers.md
。

Prerequisites

前置条件

bash

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # browser sign-in (recommended)

bash

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # 浏览器登录（推荐）

or: cargo-ai login --token <your-api-token> # workspace-scoped API token (non-interactive)

或：cargo-ai login --token <your-api-token> # 工作区范围的API令牌（非交互式）

Pin a default workspace at login (with --oauth)

登录时固定默认工作区（使用--oauth）

cargo-ai login --oauth --workspace-uuid <uuid>


Verify with `cargo-ai whoami`. All commands output JSON to stdout. Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

Failed commands exit non-zero and return `{"errorMessage": "..."}`.

cargo-ai login --oauth --workspace-uuid <uuid>


使用`cargo-ai whoami`验证。所有命令都会向标准输出（stdout）输出JSON。如果未全局安装，请在每个命令前添加前缀`npx @cargo-ai/cli`，替代`cargo-ai`。

执行失败的命令会返回非零退出码，并返回`{"errorMessage": "..."}`。

Discover resources first

先发现资源

bash

cargo-ai ai agent list                     # all agents (uuid, name, description)
cargo-ai ai template list                  # all AI agent templates (slug, name)
cargo-ai ai file list                      # all uploaded files (uuid, name, contentType)
cargo-ai ai mcp-server list                # all MCP servers (uuid, name)
cargo-ai ai memory list --scope agent --agent-uuid <uuid>  # agent memories

Retrieve in the UI: agents live at

app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>

. Get

<WORKSPACE_UUID>

from

cargo-ai whoami

under

workspace.uuid

bash

cargo-ai ai agent list                     # 所有Agent（uuid、名称、描述）
cargo-ai ai template list                  # 所有AI Agent模板（slug、名称）
cargo-ai ai file list                      # 所有已上传文件（uuid、名称、contentType）
cargo-ai ai mcp-server list                # 所有MCP服务器（uuid、名称）
cargo-ai ai memory list --scope agent --agent-uuid <uuid>  # Agent记忆

在UI中检索：Agent位于

app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>

。可从

cargo-ai whoami

的

workspace.uuid

字段获取

<WORKSPACE_UUID>

。

Quick reference

快速参考

bash

cargo-ai ai agent list
cargo-ai ai agent get <agent-uuid>
cargo-ai ai agent create --name <name> --icon-color blue --icon-face 🤖
cargo-ai ai agent update --uuid <agent-uuid> --name <name>
cargo-ai ai agent remove <agent-uuid>
cargo-ai ai release list --agent-uuid <uuid>
cargo-ai ai release get <release-uuid>
cargo-ai ai release get-draft --agent-uuid <uuid>
cargo-ai ai release update-draft --agent-uuid <uuid> --language-model-slug gpt-4o
cargo-ai ai release deploy-draft --agent-uuid <uuid>
cargo-ai ai template list
cargo-ai ai template get <slug>
cargo-ai ai file list
cargo-ai ai file upload --file-path ./knowledge-base.pdf
cargo-ai ai file update --uuid <file-uuid> --name "Updated Name"
cargo-ai ai file remove <file-uuid>
cargo-ai ai mcp-server list
cargo-ai ai mcp-server create --name "Internal Tools"
cargo-ai ai mcp-server update --uuid <mcp-server-uuid> --name "Updated Name"
cargo-ai ai mcp-server remove <mcp-server-uuid>
cargo-ai ai memory list --scope agent --agent-uuid <uuid>
cargo-ai ai memory update --mem0-id <id> --scope agent --agent-uuid <uuid> --content "Updated memory"
cargo-ai ai memory remove --mem0-id <id> --scope agent --agent-uuid <uuid>

bash

cargo-ai ai agent list
cargo-ai ai agent get <agent-uuid>
cargo-ai ai agent create --name <name> --icon-color blue --icon-face 🤖
cargo-ai ai agent update --uuid <agent-uuid> --name <name>
cargo-ai ai agent remove <agent-uuid>
cargo-ai ai release list --agent-uuid <uuid>
cargo-ai ai release get <release-uuid>
cargo-ai ai release get-draft --agent-uuid <uuid>
cargo-ai ai release update-draft --agent-uuid <uuid> --language-model-slug gpt-4o
cargo-ai ai release deploy-draft --agent-uuid <uuid>
cargo-ai ai template list
cargo-ai ai template get <slug>
cargo-ai ai file list
cargo-ai ai file upload --file-path ./knowledge-base.pdf
cargo-ai ai file update --uuid <file-uuid> --name "Updated Name"
cargo-ai ai file remove <file-uuid>
cargo-ai ai mcp-server list
cargo-ai ai mcp-server create --name "Internal Tools"
cargo-ai ai mcp-server update --uuid <mcp-server-uuid> --name "Updated Name"
cargo-ai ai mcp-server remove <mcp-server-uuid>
cargo-ai ai memory list --scope agent --agent-uuid <uuid>
cargo-ai ai memory update --mem0-id <id> --scope agent --agent-uuid <uuid> --content "Updated memory"
cargo-ai ai memory remove --mem0-id <id> --scope agent --agent-uuid <uuid>

Agents

Agent

Agents are AI resources with configured instructions, a language model, actions, and optional resources.

Before creating an agent from scratch, check existing templates — they capture proven patterns for common use cases (lead research, classification, email drafting) and give you a ready-made system prompt, model, and temperature to start from:

bash

cargo-ai ai template list          # browse available patterns
cargo-ai ai template get <slug>    # inspect system prompt, model, and actions

bash

undefined

Agent是具备配置指令、语言模型、操作及可选资源的AI资源。

从零创建Agent之前，请先查看现有模板——它们涵盖了常见用例（潜在客户调研、分类、邮件撰写）的成熟模式，可为你提供现成的系统提示词、模型和温度系数作为起点：

bash

cargo-ai ai template list          # 浏览可用模式
cargo-ai ai template get <slug>    # 查看系统提示词、模型和操作

bash

undefined

List all agents

列出所有Agent

cargo-ai ai agent list

Get a single agent (includes deployed release details)

获取单个Agent（包含已部署版本的详细信息）

cargo-ai ai agent get <agent-uuid>

Create an agent

创建Agent

cargo-ai ai agent create
--name "Lead Researcher"
--icon-color blue --icon-face 🤖
--description "Researches leads and enriches data"

cargo-ai ai agent create
--name "潜在客户研究员"
--icon-color blue --icon-face 🤖
--description "调研潜在客户并丰富数据"

Update an agent

更新Agent

cargo-ai ai agent update --uuid <agent-uuid>
--name "Senior Lead Researcher"
--description "Updated description"

cargo-ai ai agent update --uuid <agent-uuid>
--name "资深潜在客户研究员"
--description "更新后的描述"

Move to a folder (find folder UUIDs via cargo-workspace-management)

移动到文件夹（通过cargo-workspace-management获取文件夹UUID）

cargo-ai ai agent update --uuid <agent-uuid> --folder-uuid <folder-uuid>

Remove an agent

删除Agent

cargo-ai ai agent remove <agent-uuid>


**Agent icon:** `--icon-color` must be one of: `grey`, `green`, `purple`, `yellow`, `blue`, `red`. `--icon-face` is an emoji string.

**Folders:** Folder creation, listing, and management lives in [`cargo-workspace-management`](../cargo-workspace-management/SKILL.md) (`cargo-ai workspaceManagement folder list/create/...`). Use that skill to discover or create the `<folder-uuid>` you pass to `--folder-uuid` here.

cargo-ai ai agent remove <agent-uuid>


**Agent图标**：`--icon-color`必须是以下选项之一：`grey`、`green`、`purple`、`yellow`、`blue`、`red`。`--icon-face`为表情字符串。

**文件夹**：文件夹的创建、列出和管理功能在[`cargo-workspace-management`](../cargo-workspace-management/SKILL.md)中（`cargo-ai workspaceManagement folder list/create/...`）。使用该技能查找或创建要传递给`--folder-uuid`的`<folder-uuid>`。

Releases

版本（Releases）

Releases are versioned snapshots of an agent's configuration (system prompt, actions, resources, model, temperature). Agents execute against their deployed release.

bash

undefined

版本是Agent配置（系统提示词、操作、资源、模型、温度系数）的版本化快照。Agent会基于其已部署的版本执行。

bash

undefined

List releases for an agent

列出Agent的所有版本

cargo-ai ai release list --agent-uuid <uuid>

Get a specific release

获取特定版本

cargo-ai ai release get <release-uuid>

Get the current draft release (editable)

获取当前草稿版本（可编辑）

cargo-ai ai release get-draft --agent-uuid <uuid>

Update the draft release

更新草稿版本

cargo-ai ai release update-draft --agent-uuid <uuid>
--system-prompt "You are a lead research assistant..."
--language-model-slug gpt-4o
--temperature 0.3
--max-steps 10

cargo-ai ai release update-draft --agent-uuid <uuid>
--system-prompt "你是一名潜在客户研究助手..."
--language-model-slug gpt-4o
--temperature 0.3
--max-steps 10

Deploy the draft release (makes it live)

部署草稿版本（使其生效）

cargo-ai ai release deploy-draft --agent-uuid <uuid>
--integration-slug openai
--language-model-slug gpt-4o
--actions '[]'
--mcp-clients '[]'
--resources '[]'
--capabilities '[]'
--suggested-actions '[]'
--description "Added research actions"


**Agent configuration workflow:**

1. **Browse templates for inspiration**: `cargo-ai ai template list` — find a template close to your use case, then `cargo-ai ai template get <slug>` to see its system prompt, model, and temperature
2. Create the agent: `cargo-ai ai agent create --name "..." --icon-color blue --icon-face 🤖`
3. Get the draft release: `cargo-ai ai release get-draft --agent-uuid <uuid>`
4. Update the draft with configured actions, resources, prompt, model: `cargo-ai ai release update-draft --agent-uuid <uuid> ...`
5. Deploy: `cargo-ai ai release deploy-draft --agent-uuid <uuid> ...`


**Agent配置流程**：

1. **浏览模板获取灵感**：`cargo-ai ai template list`——找到与你的用例接近的模板，然后使用`cargo-ai ai template get <slug>`查看其系统提示词、模型和温度系数
2. 创建Agent：`cargo-ai ai agent create --name "..." --icon-color blue --icon-face 🤖`
3. 获取草稿版本：`cargo-ai ai release get-draft --agent-uuid <uuid>`
4. 使用配置的操作、资源、提示词、模型更新草稿：`cargo-ai ai release update-draft --agent-uuid <uuid> ...`
5. 部署：`cargo-ai ai release deploy-draft --agent-uuid <uuid> ...`

Templates

模板

Templates are pre-built agent configurations that capture proven patterns for common use cases. Always check templates before designing an agent from scratch — they give you a ready-made system prompt, recommended language model, temperature, and tool configuration that you can adopt as-is or adapt.

bash

undefined

模板是预构建的Agent配置，涵盖了常见用例的成熟模式。从零设计Agent之前务必先查看模板——它们可为你提供现成的系统提示词、推荐语言模型、温度系数和工具配置，你可以直接采用或按需调整。

bash

undefined

List available agent templates

列出可用的Agent模板

cargo-ai ai template list

Get a template by slug — inspect its system prompt, model, and settings

通过slug获取模板——查看其系统提示词、模型和设置

cargo-ai ai template get <slug>


Templates include a system prompt, actions, resources, and recommended model settings. Use them as a starting point and customize via `release update-draft`. See `references/examples/templates.md` for the full guide including an end-to-end example of creating an agent from a template.

cargo-ai ai template get <slug>


模板包含系统提示词、操作、资源和推荐模型设置。将其作为起点，通过`release update-draft`进行自定义。完整指南（包括从模板创建Agent的端到端示例）请查看`references/examples/templates.md`。

Model and temperature guidance

模型和温度系数指南

Use case	Recommended model	Temperature
Classification, extraction, scoring	`gpt-4o-mini` or `claude-3-5-haiku`	`0.0` – `0.2`
Research, summarization, analysis	`gpt-4o` or `claude-3-5-sonnet`	`0.2` – `0.5`
Copywriting, personalization	`gpt-4o` or `claude-3-5-sonnet`	`0.5` – `0.8`
Brainstorming, creative ideation	`gpt-4o` or `claude-opus`	`0.7` – `1.0`

Low temperature (

0.0

–

0.2

) = deterministic, consistent outputs. High temperature (

0.7

+) = creative, varied outputs. For production workflows processing thousands of records, prefer low temperature.

使用场景	推荐模型	温度系数
分类、提取、评分	`gpt-4o-mini` 或 `claude-3-5-haiku`	`0.0` – `0.2`
调研、摘要、分析	`gpt-4o` 或 `claude-3-5-sonnet`	`0.2` – `0.5`
文案撰写、个性化内容	`gpt-4o` 或 `claude-3-5-sonnet`	`0.5` – `0.8`
头脑风暴、创意构思	`gpt-4o` 或 `claude-opus`	`0.7` – `1.0`

低温度系数（

0.0

–

0.2

）= 确定性、一致性输出。高温度系数（

0.7

+）= 创造性、多样化输出。对于处理数千条记录的生产工作流，建议使用低温度系数。

Files

文件

Upload files (PDFs, CSVs, text) for retrieval-augmented generation (RAG). Agents reference uploaded files to ground their responses in specific knowledge.

bash

undefined

上传文件（PDF、CSV、文本）用于检索增强生成（RAG）。Agent会引用已上传的文件，让回复基于特定知识库。

bash

undefined

List all files

列出所有文件

cargo-ai ai file list

Upload a file

上传文件

cargo-ai ai file upload --file-path ./knowledge-base.pdf

Update a file's name or folder

更新文件名称或所在文件夹

cargo-ai ai file update --uuid <file-uuid> --name "Q1 Research Notes" cargo-ai ai file update --uuid <file-uuid> --folder-uuid <folder-uuid>

cargo-ai ai file update --uuid <file-uuid> --name "Q1调研笔记" cargo-ai ai file update --uuid <file-uuid> --folder-uuid <folder-uuid>

Remove a file

删除文件

cargo-ai ai file remove <file-uuid>


Uploaded files are attached to agents via the release's `resources` configuration. Use `release update-draft` to add file resources to an agent.

cargo-ai ai file remove <file-uuid>


已上传的文件通过版本的`resources`配置附加到Agent。使用`release update-draft`将文件资源添加到Agent。

MCP servers

MCP服务器

MCP (Model Context Protocol) servers expose additional actions to agents. Once connected, agents can call MCP actions automatically during conversations or workflow runs.

bash

undefined

MCP（模型上下文协议）服务器为Agent提供额外操作。连接后，Agent可在对话或工作流运行期间自动调用MCP操作。

bash

undefined

List all MCP servers

列出所有MCP服务器

cargo-ai ai mcp-server list

Create an MCP server

创建MCP服务器

cargo-ai ai mcp-server create --name "Internal Tools"

cargo-ai ai mcp-server create --name "内部工具"

Update an MCP server

更新MCP服务器

cargo-ai ai mcp-server update --uuid <mcp-server-uuid> --name "Updated Tools"

cargo-ai ai mcp-server update --uuid <mcp-server-uuid> --name "更新后的工具"

Remove an MCP server

删除MCP服务器

cargo-ai ai mcp-server remove <mcp-server-uuid>


MCP clients (connections to MCP servers) are configured on agent releases. Use `release update-draft` to attach MCP clients to an agent.

cargo-ai ai mcp-server remove <mcp-server-uuid>


MCP客户端（与MCP服务器的连接）在Agent版本上配置。使用`release update-draft`将MCP客户端附加到Agent。

Memories

记忆

Memories are pieces of information an agent stores from conversations for future reference. They can be scoped to a workspace, user, or specific agent.

bash

undefined

记忆是Agent从对话中存储的信息，供未来参考。记忆的作用范围可以是工作区、用户或特定Agent。

bash

undefined

List agent memories

列出Agent记忆

cargo-ai ai memory list --scope agent --agent-uuid <uuid>

List workspace-wide memories

列出工作区范围的记忆

cargo-ai ai memory list --scope workspace

List user-scoped memories

列出用户范围的记忆

cargo-ai ai memory list --scope user

Update a memory

更新记忆

cargo-ai ai memory update
--mem0-id <id>
--scope agent --agent-uuid <uuid>
--content "Updated memory content"

cargo-ai ai memory update
--mem0-id <id>
--scope agent --agent-uuid <uuid>
--content "更新后的记忆内容"

Remove a memory

删除记忆

cargo-ai ai memory remove
--mem0-id <id>
--scope agent --agent-uuid <uuid>

undefined

cargo-ai ai memory remove
--mem0-id <id>
--scope agent --agent-uuid <uuid>

undefined

Help

帮助

Every command supports

--help

bash

cargo-ai ai agent create --help
cargo-ai ai release update-draft --help
cargo-ai ai file upload --help
cargo-ai ai mcp-server create --help
cargo-ai ai memory list --help

每个命令都支持

--help

：

bash

cargo-ai ai agent create --help
cargo-ai ai release update-draft --help
cargo-ai ai file upload --help
cargo-ai ai mcp-server create --help
cargo-ai ai memory list --help