Cargo Ai

Cargo CLI — AI

Agent resource management: creating and configuring agents, attaching knowledge 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 uploading knowledge files and building knowledge libraries (the content domain), use `cargo-content`. This skill covers how that knowledge attaches to an agent.

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/mcp-servers.md for MCP server creation and management examples.

Prerequisites

See `../cargo/references/prerequisites.md` for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below.

Discover resources first

cargo-ai ai agent list                     # all agents (uuid, name, description)
cargo-ai ai template list                  # all AI agent templates (slug, name)
cargo-ai ai mcp-server list                # all MCP servers (uuid, name)
cargo-ai ai memory list --scope agent --agent-uuid <uuid>  # agent memories
# Knowledge files & libraries live in the content domain — see cargo-content:
#   cargo-ai content file list   /   cargo-ai content library list

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.

Quick reference

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 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

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:

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

# List all agents
cargo-ai ai agent list

# Get a single agent (includes deployed release details)
cargo-ai ai agent get <agent-uuid>

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

# Update an agent
cargo-ai ai agent update --uuid <agent-uuid> \
  --name "Senior Lead Researcher" \
  --description "Updated description"

# Move to a folder (find folder UUIDs via cargo-workspace-management)
cargo-ai ai agent update --uuid <agent-uuid> --folder-uuid <folder-uuid>

# Remove an 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-ai workspaceManagement folder list/create/...). Use that skill to discover or create the <folder-uuid> you pass to --folder-uuid here.

Releases

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

# List releases for an 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

# 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"

Structured output & heartbeat — not yet exposed as CLI flags

The release API payload (both draft/update and draft/deploy) accepts two fields that `release update-draft` / `release deploy-draft` do not surface as flags (verified against the CLI source — there is no --output / --output-schema or --heartbeat):

The generic --options flag does not carry these — the API's options only holds {connectorUuidsByIntegrationSlug, modelUuidsByIntegrationSlug}. Until the flags ship, set these with a direct API call against the same endpoints the CLI uses:

# Structured (JSON Schema) output on the draft release
curl -sS -X PUT "$CARGO_API_BASE/v1/ai/releases/draft/update" \
  -H "Authorization: Bearer $CARGO_TOKEN" -H "Content-Type: application/json" \
  -d '{"agentUuid":"<uuid>","output":{"type":"jsonSchema","jsonSchema":{"type":"object","properties":{"score":{"type":"number"}},"required":["score"]}}}'
# Deploy carries the same fields — POST .../v1/ai/releases/draft/deploy

Send these payloads alongside the other fields you're updating (the endpoint replaces the draft config). File a `workspaceManagement report` (see `../cargo-workspace-management/SKILL.md`) to request first-class --output / --heartbeat flags — this is the documented feedback channel for CLI/UI parity gaps.

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> ...

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.

# List available agent templates
cargo-ai ai template list

# Get a template by slug — inspect its system prompt, model, and settings
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.

Model and temperature guidance

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.

Knowledge for RAG (files & libraries)

Knowledge that grounds agent responses (retrieval-augmented generation, RAG) comes from the `content` domain — see `cargo-content`:

• Files — uploaded binaries (PDFs, CSVs, text).
• Libraries — collections that group files, either native (workspace-managed) or connector-backed (synced from an external source via an unstructured-data extractor).

Files and libraries moved out of ai into the top-level `content` domain in CLI ≥ 1.0.19 (cargo-ai content file … / cargo-ai content library …). The old ai file … commands are gone. Everything content-related now lives in `cargo-content`.

Attaching knowledge to an agent

A file or library is inert until attached to an agent via the draft release's resources array and deployed. Upload files / build libraries in `cargo-content`, then wire them in here with release update-draft --resources … followed by release deploy-draft. See `../cargo-content/references/examples/files.md` for the full upload → attach → deploy sequence.

MCP servers

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

# List all MCP servers
cargo-ai ai mcp-server list

# Create an MCP server
cargo-ai ai mcp-server create --name "Internal Tools"

# Update an MCP server
cargo-ai ai mcp-server update --uuid <mcp-server-uuid> --name "Updated Tools"

# Remove an MCP server
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.

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.

# List agent memories
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"

# Remove a memory
cargo-ai ai memory remove \
  --mem0-id <id> \
  --scope agent --agent-uuid <uuid>

Help

Every command supports --help:

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

Agent examples

List all agents

cargo-ai ai agent list

Find an agent by name

cargo-ai ai agent list
# → Scan the "name" fields in the response to find the target agent UUID

Create an agent

cargo-ai ai agent create \
  --name "Lead Researcher" \
  --icon-color purple --icon-face 🔍 \
  --description "Researches and qualifies leads using web data"

Create an agent in a folder

Folders are managed by the `cargo-workspace-management` skill — see its references/examples/folders.md for create/list/update.

cargo-ai workspaceManagement folder list
# → Find the folder UUID (kind: "agent")

cargo-ai ai agent create \
  --name "Lead Researcher" \
  --icon-color purple --icon-face 🔍 \
  --folder-uuid <folder-uuid>

Configure and deploy an agent (full workflow)

# 1. Create the agent
cargo-ai ai agent create \
  --name "Company Scorer" \
  --icon-color green --icon-face 📊
# → agent.uuid

# 2. Get the draft release
cargo-ai ai release get-draft --agent-uuid <agent-uuid>
# → release.uuid

# 3. Configure the draft: set model, temperature, prompt
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --language-model-slug gpt-4o-mini \
  --temperature 0.0 \
  --max-steps 5 \
  --system-prompt "You are a company scoring assistant. Given a company record, score it from 1-10 based on fit criteria."

# 4. Deploy the draft
cargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \
  --integration-slug openai \
  --language-model-slug gpt-4o-mini \
  --actions '[]' \
  --mcp-clients '[]' \
  --resources '[]' \
  --capabilities '[]' \
  --suggested-actions '[]' \
  --description "Initial deployment with scoring prompt"

Update an agent's name and description

cargo-ai ai agent update --uuid <agent-uuid> \
  --name "Senior Lead Researcher" \
  --description "Advanced lead research with enrichment capabilities"

Move an agent to a different folder

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

Remove an agent

cargo-ai ai agent remove <agent-uuid>

Create an agent from a template

# 1. Browse templates
cargo-ai ai template list

# 2. Get the template
cargo-ai ai template get <template-slug>
# → Copy the systemPrompt, actions, resources, model settings

# 3. Create the agent
cargo-ai ai agent create \
  --name "My Custom Agent" \
  --icon-color blue --icon-face 🤖

# 4. Apply template settings to the draft
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --system-prompt "<from template>" \
  --language-model-slug <from template> \
  --temperature <from template>

# 5. Deploy
cargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \
  --integration-slug <from template> \
  --language-model-slug <from template> \
  --actions '[]' \
  --mcp-clients '[]' \
  --resources '[]' \
  --capabilities '[]' \
  --suggested-actions '[]'

List releases for an agent

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

View the current live configuration

cargo-ai ai agent get <agent-uuid>
# → .deployedRelease contains the full live config (prompt, model, actions, resources)

MCP server examples

List all MCP servers

cargo-ai ai mcp-server list

Create an MCP server

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

Connect an MCP server to an agent

MCP servers are connected to agents as MCP clients on the release:

# 1. Create or find the MCP server
cargo-ai ai mcp-server list
# → mcp-server-uuid

# 2. Add as an MCP client on the agent's draft release
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --mcp-clients '[{"kind":"custom","name":"Internal Tools","url":"https://mcp.example.com","authentication":null,"disabledToolSlugs":[]}]'

# 3. Deploy
cargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \
  --language-model-slug gpt-4o \
  --integration-slug openai

MCP client kinds:

• custom — URL-based MCP server. Requires name, url, and optionally authentication.
• connector — Integration-backed MCP client. Requires name, connectorUuid, integrationSlug.

Connect a connector-backed MCP client

# 1. Find the connector
cargo-ai connection connector list
# → connector-uuid, integrationSlug

# 2. Add as an MCP client
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --mcp-clients '[{"kind":"connector","name":"HubSpot Tools","connectorUuid":"<connector-uuid>","integrationSlug":"hubspot","disabledToolSlugs":[]}]'

# 3. Deploy
cargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \
  --language-model-slug gpt-4o \
  --integration-slug openai

Disable specific actions from an MCP server

Use disabledToolSlugs to prevent the agent from using specific MCP actions:

cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --mcp-clients '[{"kind":"custom","name":"Internal Tools","url":"https://mcp.example.com","authentication":null,"disabledToolSlugs":["dangerous_tool","admin_tool"]}]'

Update an MCP server name

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

Remove an MCP server

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

AI template examples

What is an AI template?

An AI template is a pre-built agent configuration — a ready-to-use agent blueprint with instructions, model settings, and action configuration already defined. Templates capture common agent patterns (lead research, company classification, email drafting) so you don't have to configure an agent from scratch.

Always check templates before creating an agent. Even if no template is a perfect match, they provide:

• A proven system prompt structure for the use case
• A recommended language model and temperature setting
• A list of actions and resources to consider attaching

AI templates are read-only. You discover them by listing, then use their configuration as a starting point when creating or updating an agent.

List all AI templates

cargo-ai ai template list

Response:

{
  "templates": [
    {
      "slug": "lead-researcher",
      "name": "Lead Researcher",
      "description": "Researches a prospect's company, role, and contact details",
      "languageModelSlug": "gpt-4o",
      "temperature": 0.3
    },
    {
      "slug": "company-classifier",
      "name": "Company Classifier",
      "description": "Classifies a company by industry, size, and ICP fit",
      "languageModelSlug": "gpt-4.1-mini",
      "temperature": 0.1
    },
    {
      "slug": "email-drafter",
      "name": "Email Drafter",
      "description": "Drafts personalised outbound emails based on enrichment data",
      "languageModelSlug": "gpt-4o",
      "temperature": 0.7
    }
  ]
}

Key fields:

• `slug` — identifier for reference
• `name` — human-readable name
• `description` — what the agent does
• `languageModelSlug` — recommended model for this use case
• `temperature` — recommended temperature setting

Use a template to create an agent

The standard pattern:

1. List templates to find the right one 2. Create a new agent using the template's recommended settings 3. Attach any files or MCP servers the agent needs 4. Start chatting or embed the agent in a workflow

# 1. Find the right template
cargo-ai ai template list
# → Find "lead-researcher"

# 2. Create an agent
cargo-ai ai agent create \
  --name "Lead Researcher" \
  --icon-color purple --icon-face 🔍
# → Extract agent.uuid

# 3. Configure the draft release with template settings
cargo-ai ai release update-draft --agent-uuid <agent-uuid> \
  --system-prompt "You are a research assistant. Given a company domain and a contact name, find their role, LinkedIn profile, and email address. Be concise and structured." \
  --language-model-slug gpt-4o \
  --temperature 0.3

# 4. Attach a knowledge file (optional)
cargo-ai content file upload --file-path ./icp-criteria.pdf
# → Extract file.uuid — attach to agent via release update-draft --resources

# 5. Test with a message
cargo-ai ai chat create \
  --trigger '{"type":"draft"}' \
  --agent-uuid <agent-uuid> \
  --name "Test session"
# → Extract chat.uuid

cargo-ai ai message create \
  --chat-uuid <chat-uuid> \
  --parts '[{"type":"text","text":"Research the VP of Sales at acme.com"}]'
# → Poll with: cargo-ai ai message get <assistant-msg-uuid>

Use a template to configure an agent in a workflow node

AI templates also inform how to configure an inline agent node inside a workflow node graph. Use the template's languageModelSlug and temperature in the node's advancedSettings:

{
  "uuid": "ab12cd34-ab12-4ab1-aab1-ab12cd34ef56",
  "slug": "research_lead",
  "kind": "native",
  "actionSlug": "agent",
  "config": {
    "prompt": {
      "kind": "templateExpression",
      "expression": "Research the person {{nodes.start.first_name}} {{nodes.start.last_name}} at {{nodes.start.domain}}. Return their role, LinkedIn URL, and a 2-sentence summary.",
      "instructTo": "none",
      "fromRecipe": false
    },
    "advancedSettings": {
      "languageModelSlug": "gpt-4o",
      "temperature": 0.3,
      "maxSteps": 5
    }
  },
  "childrenUuids": ["cd34ef56-cd34-4cd3-acd3-cd34ef567890"],
  "fallbackOnFailure": false,
  "position": { "x": 0, "y": 166 }
}

See cargo-orchestration/references/nodes.md for the full node creation guide.

Template-to-agent quick reference

Response shapes

JSON response structures returned by Cargo CLI commands used in the cargo-ai skill.

cargo-ai ai agent list

{
  "agents": [
    {
      "uuid": "agent-uuid",
      "workspaceUuid": "...",
      "name": "Sales Research Agent",
      "icon": { "color": "blue", "face": "🤖" },
      "description": "Researches leads and enriches data",
      "triggers": [],
      "deployedRelease": {
        "uuid": "release-uuid",
        "version": "3",
        "description": "Added email step",
        "systemPrompt": "You are a sales research assistant...",
        "languageModelSlug": "gpt-4o",
        "integrationSlug": "openai",
        "temperature": 0.3,
        "maxSteps": 10,
        "actions": [],
        "resources": [],
        "capabilities": [],
        "mcpClients": [],
        "deployedAt": "2025-01-10T09:00:00Z",
        "createdAt": "2025-01-10T09:00:00Z"
      },
      "folderUuid": null,
      "template": null,
      "isReadOnly": false,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  ]
}

Key fields: uuid (needed for chat create, release operations), name (match by name), deployedRelease (current live config — null if never deployed).

Agent icon colors: grey, green, purple, yellow, blue, red.

cargo-ai ai agent get

Same structure as a single item from agent list, nested under agent:

{
  "agent": {
    "uuid": "agent-uuid",
    "name": "Sales Research Agent",
    "icon": { "color": "blue", "face": "🤖" },
    "deployedRelease": { ... },
    ...
  }
}

cargo-ai ai release list

{
  "releases": [
    {
      "uuid": "release-uuid",
      "agentUuid": "agent-uuid",
      "version": "3",
      "status": "deployed",
      "description": "Added research actions",
      "systemPrompt": "You are a sales research assistant...",
      "languageModelSlug": "gpt-4o",
      "integrationSlug": "openai",
      "temperature": 0.3,
      "maxSteps": 10,
      "withReasoning": false,
      "actions": [],
      "resources": [],
      "capabilities": [],
      "suggestedActions": [],
      "mcpClients": [],
      "deployedAt": "2025-01-10T09:00:00Z",
      "createdAt": "2025-01-10T09:00:00Z",
      "updatedAt": "2025-01-10T09:00:00Z"
    }
  ]
}

Status values: draft, deployed, archived.

Supports --agent-uuid, --limit, --offset.

cargo-ai ai release get

{
  "release": {
    "uuid": "release-uuid",
    "agentUuid": "agent-uuid",
    "version": "3",
    "status": "deployed",
    "description": "Added research actions",
    "systemPrompt": "You are a sales research assistant...",
    "languageModelSlug": "gpt-4o",
    "integrationSlug": "openai",
    "connectorUuid": null,
    "temperature": 0.3,
    "maxSteps": 10,
    "withReasoning": false,
    "actions": [
      {
        "kind": "connector",
        "integrationSlug": "clearbit",
        "connectorUuid": "connector-uuid",
        "actionSlug": "company_enrich",
        "slug": "enrich_company",
        "name": "Enrich Company",
        "description": "Enriches company data",
        "isBulkAllowed": false,
        "config": {}
      }
    ],
    "resources": [
      {
        "kind": "file",
        "slug": "knowledge_base",
        "name": "Knowledge Base",
        "description": null,
        "prompt": null,
        "items": [{ "kind": "file", "fileUuid": "file-uuid" }]
      }
    ],
    "capabilities": [],
    "suggestedActions": [],
    "mcpClients": [
      {
        "kind": "custom",
        "name": "Internal Tools",
        "url": "https://mcp.example.com",
        "authentication": null,
        "disabledToolSlugs": []
      }
    ],
    "deployedAt": "2025-01-10T09:00:00Z",
    "createdAt": "2025-01-10T09:00:00Z",
    "updatedAt": "2025-01-10T09:00:00Z"
  }
}

Key fields: actions (array of tool/connector/agent actions), resources (file or model resources), mcpClients (MCP server connections), systemPrompt, languageModelSlug, temperature, maxSteps.

Action kinds: tool (workflow tool), connector (integration action), agent (sub-agent).

Resource kinds: file (uploaded files/folders), model (data model reference).

MCP client kinds: custom (URL-based), connector (integration-backed).

cargo-ai ai template list

{
  "templates": [
    {
      "slug": "lead-researcher",
      "name": "Lead Researcher",
      "description": "Researches and qualifies leads using web data",
      "scope": "public",
      "isPreset": true,
      "kind": "agent",
      "icon": { "color": "purple", "face": "🔍" },
      "languageModelSlug": "gpt-4o",
      "temperature": 0.3,
      "categories": ["prospecting"],
      "author": {
        "name": "Cargo",
        "title": "Platform",
        "company": { "name": "Cargo", "url": "https://getcargo.ai" }
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  ]
}

Key fields: slug (used for template get), name, languageModelSlug, temperature.

Template categories: prospecting, ops, enablement, outreach, expansion, public, private.

cargo-ai ai template get

{
  "template": {
    "slug": "lead-researcher",
    "name": "Lead Researcher",
    "kind": "agent",
    "description": "...",
    "systemPrompt": "You are a lead research assistant...",
    "languageModelSlug": "gpt-4o",
    "integrationSlug": "openai",
    "temperature": 0.3,
    "maxSteps": 10,
    "withReasoning": false,
    "actions": [...],
    "resources": [...],
    "capabilities": [],
    "suggestedActions": [],
    "icon": { "color": "purple", "face": "🔍" },
    "scope": "public",
    "isPreset": true,
    "categories": ["prospecting"],
    "author": { ... },
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-15T00:00:00Z"
  }
}

Content files & libraries (cargo-ai content file … / content library …) live in the `cargo-content` skill — see cargo-content/references/response-shapes.md for their shapes.

cargo-ai ai mcp-server list

{
  "mcpServers": [
    {
      "uuid": "mcp-server-uuid",
      "workspaceUuid": "...",
      "name": "Internal Tools",
      "actions": [
        {
          "kind": "tool",
          "slug": "search_docs",
          "name": "Search Docs",
          "description": "Searches internal documentation",
          "isBulkAllowed": false,
          "config": {}
        }
      ],
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  ]
}

Key fields: uuid, name, actions (discovered actions from the MCP server).

cargo-ai ai memory list

{
  "memories": [
    {
      "mem0Id": "memory-id",
      "content": "The user prefers concise responses with bullet points",
      "scope": "agent",
      "agentUuid": "agent-uuid",
      "workspaceUuid": "...",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Memory scopes:

• workspace — shared across all agents and users in the workspace. Has workspaceUuid.
• user — specific to a user. Has userUuid.
• agent — specific to an agent. Has agentUuid and workspaceUuid.

Key field: mem0Id (needed for update and remove operations).

Troubleshooting

Common errors and solutions for cargo-ai commands.

General

`{"errorMessage": "..."}` All failed commands exit non-zero and return an error JSON. Read the errorMessage for the specific issue.

`Unauthorized` / `403` Your API token may lack the required permissions. Verify with cargo-ai whoami and check that your role includes ai:agent:* or ai:agent:write actions.

Agents

`agentNotFound` The agent UUID does not exist or has been deleted. Re-run cargo-ai ai agent list to get the current list of agents.

`folderNotFound` The folder UUID passed to --folder-uuid does not exist. Folders are managed by the `cargo-workspace-management` skill — run cargo-ai workspaceManagement folder list to find valid folder UUIDs, or cargo-ai workspaceManagement folder create --kind agent ... to create one.

Agent has no deployed release If agent get shows deployedRelease: null, the agent has never been deployed. Follow the release workflow: 1. cargo-ai ai release get-draft --agent-uuid <uuid> 2. cargo-ai ai release update-draft --agent-uuid <uuid> --language-model-slug gpt-4o --system-prompt "..." 3. cargo-ai ai release deploy-draft --agent-uuid <uuid> --language-model-slug gpt-4o --integration-slug openai

Releases

`draftReleaseNotFound` The agent does not have a draft release. This can happen if the agent was just created. Try cargo-ai ai release get-draft --agent-uuid <uuid> first — it may auto-create the draft.

`invalidParent` The --parent-uuid passed to release update-draft does not match a valid release. Omit it or use a UUID from release list.

`invalidReleaseVersion` The version string is invalid. Version must be a non-empty string (not a number).

`invalidConnector` A connector UUID referenced in the release actions or configuration does not exist. Verify connector UUIDs with cargo-ai connection connector list.

`failedToReconciliateAgentAiTools` The actions configuration in the release is invalid — a referenced tool, agent, or connector UUID may not exist. Verify all UUIDs in the actions array.

Can't set structured (JSON Schema) output or a heartbeat from the CLI release update-draft / release deploy-draft have no --output / --output-schema or --heartbeat flag, even though the release API payload accepts output and heartbeat. The generic --options flag won't carry them. See the "Structured output & heartbeat" section in `../SKILL.md` for the shapes and the direct-API workaround, and file a workspaceManagement report to request the flags.

Templates

`templateNotFound` The template slug does not exist. Run cargo-ai ai template list to see available templates.

Files & libraries

Knowledge files and libraries moved to the content domain (CLI ≥ 1.0.19). For fileNotFound, folderNotFound, upload failures, and the unknown command error on the old ai file … path, see `cargo-content` → references/troubleshooting.md.

MCP Servers

`mcpServerNotFound` The MCP server UUID does not exist or has been deleted. Run cargo-ai ai mcp-server list to get the current list.

MCP actions not appearing in agent MCP servers are connected to agents via MCP clients on the release. After creating an MCP server, add it as an MCP client to the agent's draft release using release update-draft, then deploy.

Memories

`memoryNotFound` The mem0Id does not match any existing memory. Run cargo-ai ai memory list with the correct --scope and --agent-uuid to find valid memory IDs.

Wrong scope Memory operations require the correct scope. An agent-scoped memory needs --scope agent --agent-uuid <uuid>. A workspace-scoped memory needs --scope workspace. Mismatched scopes return not-found errors.