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 { 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,
  languageModel: "gpt-4o",
  systemPrompt:
    "You qualify inbound leads, enrich missing contact info, and route hot leads to Slack.",
  maxSteps: 12,
  capabilities: ["webSearch", "memory"],
  models: [{ ref: contacts, readOnly: true }],
  tools: [enrich],
  subAgents: [{ ref: enricher, waitUntilFinished: true }],
  connectorActions: [{ integration: "hunter", actionSlug: "findEmail" }],
  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
tools / connectorActionsOperations the agent can invokeTools & actions
modelsStructured data it can read/writeResources & context
subAgentsSpecialist agents it can delegate tothis page
connector / languageModel / maxSteps / evaluatorLLM provider and behaviorAdvanced settings
tools, subAgents, and connectorActions accept the same per-call options — pass a bare handle, or { ref, name, description, isBulkAllowed, waitUntilFinished } when you need to tune the call (connector actions omit waitUntilFinished).

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