Build and configure AI agents inside Cargo — create an agent, choose its model and temperature, write its prompt, attach knowledge for retrieval (RAG), connect MCP tool servers, manage memories, and deploy releases. Triggers: "create an agent", "make an agent that", "give the agent our docs", "attac

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 ](../cargo content/SKILL.md). 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 ](../cargo workspace management/SKILL.md). 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. Bootstrap Already signed in ( cargo ai whoami returns a workspace)? Skip to the next section. Every command prints JSON to stdout; failures exit non zero with {"errorMessage": "..."} . Anything that creates a run or a batch is async — pass wait until finished or poll the matching get . When the full skill bundle is installed, [ ../cargo/references/prerequisites.md ](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin only surface. Discover resources first 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 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: 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. Releases Releases are versioned snapshots of an agent's configuration (system prompt, actions, resources, model, temperature). Agents execute against their deployed release. with reasoning [true false] on update draft / deploy draft turns reasoning mode on (bare flag = true ) for models that support it. Coding agents ( harness slug , repository ) A release with a harness runs as a coding agent: each turn works in a sandbox with a git checkout instead of a plain chat loop. Harness slugs: claudeCode , codex , openCode , deepAgents . repository (JSON): connectorUuid (a GitHub connector — it identifies the user, it is not the identity the agent acts as), repository as owner/name , defaultBranch , rootDirectory , env ( [{key, type:"public", value}] or {key, type:"secret", secretValue} ), and runAsUserUuid — a service user whose temporary CARGO API TOKEN the sandbox gets (the help omits it; see [ ../cargo workspace management/SKILL.md ](../cargo workspace management/SKILL.md) → "Service users"; your permissions must cover it or the call fails 403 runAsUserNotFound / runAsUserNotPermitted ). The agent acts as the Cargo GitHub app , never as the connected user: it clones, pushes, comments and opens PRs as the app's installation. Install the app on the repo first — without it the turn fails. The sandbox's GitHub token is scoped to that one repository — any other repository is refused — lasts 1 hour, and is refreshed each turn; it is redacted from chat output but readable by the agent. It works on a branch cargo/<short name , never pushes to the default branch, never force pushes, and opens or updates the PR through its own PR tool, which links the PR to the chat. A mention of the app on a PR the agent's chat opened continues that same chat — no trigger needed (skipped if the chat moved to another repository, or another agent opened the PR). Close the chat to stop it. The GitHub trigger adds allPullRequests (answer mentions on any PR in the repo), fixFailedChecks (+ maxCheckFixAttempts 1–10, reset when someone mentions or reviews) and addressReviews , all default false . Per chat instead of per release. ai chat create harness slug … repository … and ai message create (for the chat it auto creates) take the same two flags; omitted, the agent's pinned release decides. They are set when the chat is created : passing either with chat uuid is a 400 — harnessSlug and repository are not allowed with chatUuid: they are set when the chat is created. Create a new chat to use another harness or repository. A message sent to a chat that is still answering is queued : 202 with userMessage and no assistant message yet; the reply follows once the turn ahead finishes ( chatClosed → 409, chatNotFound → 404). Sending and polling: [ ../cargo orchestration/SKILL.md ](../cargo orchestration/SKILL.md). In a project: defineAgent({ harness, repository }) — [ ../cargo project/references/resources.md ](../cargo project/references/resources.md). 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 ): Field Shape Purpose output {"type":"text"} or {"type":"jsonSchema","jsonSchema": <standard JSON Schema object } Force the agent to return structured output matching a JSON Schema. heartbeat {"intervalMinutes": number, "maxMessages": number, "prompt": string \ null} Periodically re wake the chat ( intervalMinutes ) until it reaches maxMessages ; prompt is the wake message (null = generic "continue"). 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: draft/update is a partial update: fields you omit keep their current draft values. draft/deploy requires actions , mcpClients , resources , capabilities and suggestedActions in the body. File a workspaceManagement report (see [ ../cargo workspace management/SKILL.md ](../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 — it returns each template in full (system prompt, model, temperature, actions), so pick the one closest to your use case straight out of that response 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. 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 Use case Recommended model Temperature Classification, extraction, scoring gpt 6 luna or gpt 4o mini 0.0 – 0.2 Research, summarization, analysis gpt 6 sol or claude sonnet 5 0.2 – 0.5 Copywriting, personalization claude sonnet 5 or gpt 6 sol 0.5 – 0.8 Brainstorming, hardest reasoning claude opus 5 5 or gpt 6 astra ( claude fable 5 1 at the top end) 0.7 – 1.0 The slug must be on the connector's live list: release update draft and deploy draft fail with languageModelNotFound otherwise (checked whenever the release has a connector — the draft's default is the OpenAI one, so an Anthropic slug needs integration slug anthropic connector uuid <uuid alongside it). List what a connector offers, with each model's credits per 1,000 tokens and isReasoning , for free: Price spans three orders of magnitude ( gpt 6 luna 0.003 / 1k tokens, claude sonnet 5 0.2, claude opus 5 5 1.6, claude fable 5 1 4), so read it before picking a model for a high volume agent. claude 3 5 sonnet latest is marked deprecated in Cargo's Anthropic model list — move agents off it. 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 ](../cargo content/SKILL.md): 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 ](../cargo content/SKILL.md). 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 ](../cargo content/SKILL.md), then wire them in here with release update draft resources … followed by release deploy draft . See [ ../cargo content/references/examples/files.md ](../cargo content/references/examples/files.md) for the full upload → attach → deploy sequence. Only indexed files are searchable. A file stored with indexMode: "none" — the default for content file put , workers, the writeFile node and agent writes — can be listed and read but not searched: capability file list marks it isSearchable: false , capability file search skips it, and capability file analyze refuses it. Attach upload ed files (indexed by default) for RAG, or re write the file with index vectorStore . Letting an agent write files A file resource with "isReadOnly": false also grants capability file write on the folders it lists ( {"kind":"folder","folderUuid":"…"} items; listed files stay read only). Unset means read only. The agent writes text it produced, ≤ 1,000,000 characters , to a relative path inside one of those folders (subfolders are created) — nowhere else in the workspace. With several writable folders it must name one. Every agent write is stored private , indexMode: none and mirrorToContext: false , even when it overwrites a file someone made public. It returns { fileUuid, path, size, url } , where url is a 1 hour signed link anyone holding it can open. A write

cargo-ai