Skip to main content
An agent is an AI worker that plans and executes multi-step tasks. Unlike a play (a fixed sequence), an agent reasons over its instructions and the tools, data, and sub-agents you give it. You define one with defineAgent.

​
Define an agent

Every capability is passed as a handle, so Cargo deploys dependencies first and injects their uuids:
agents/sdr.ts
import { defineAgent } from "@cargo-ai/cdk";
import { hunter } from "../connectors/hunter";
import { openai } from "../connectors/openai";
import { contacts } from "../models/contacts";
import { enrich } from "../tools/enrich";
import { enricher } from "./enricher";

export const sdr = defineAgent("sdr", {
  connector: openai, // the LLM provider (not a `use`)
  languageModel: "gpt-4o",
  systemPrompt:
    "You qualify inbound leads, enrich missing contact info, and route hot leads to Slack.",
  maxSteps: 12,
  capabilities: ["webSearch", "memory"],
  // Everything the agent can call or read — one array, kind inferred per handle:
  uses: [
    { ref: contacts, readOnly: true }, //          a data model
    enrich, //                                     a tool
    { ref: enricher, waitUntilFinished: true }, //  a sub-agent
    hunter.actions.findEmail, //                           a connector action
  ],
  triggers: [{ type: "cron", cron: "0 9 * * *", text: "Daily qualification" }],
  evaluator: { rubric: "Did it correctly qualify the lead?", threshold: 0.8 },
});

​
Anatomy

FieldRoleLearn more
systemPromptThe agent’s mission and constraintsPrompt
capabilitiesBuilt-in LLM features (web search, memory, …)Native LLM capabilities
usesEverything it can invoke or read — tools, connector actions, sub-agents, data modelsTools & actions, Resources & context
connector / languageModel / maxSteps / evaluatorLLM provider and behaviorAdvanced settings
Each uses entry is a handle — its kind is read from the handle, so order doesn’t matter. Pass a bare handle, or { ref, …options } to tune it: tools / sub-agents / connector actions take { name, description, isBulkAllowed, waitUntilFinished }; a data model takes { readOnly, columns, prompt }. A connector action is an action off a connector handle — hunter.actions.findEmail.

​
Deploy and chat

cargo-ai cdk deploy
cargo-ai ai agent list                    # → agentUuid
cargo-ai ai chat create --agent-uuid <uuid> --trigger '{"type":"draft"}' --name "My chat"
cargo-ai ai message create --chat-uuid <uuid> \
  --parts '[{"type":"text","text":"Qualify acme.com"}]' --wait-until-finished

​
Where agents run

Agents can be triggered from plays (scheduled or change-driven), Slack mentions, the Chrome extension, embedded chat, or a CRM button. Bundle them behind an MCP server to expose them to external assistants.

​
Using the UI

Prefer to build visually? See Using the UI for the Instructions / Actions / Resources walkthrough. Agents built in code and in the UI are interchangeable.