> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> LLM-powered workers that reason, research, and act. Define them with defineAgent — wiring in tools, data models, sub-agents, and connector actions through one `uses` array.

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:

```ts agents/sdr.ts theme={null}
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

| Field                                                    | Role                                                                                 | Learn more                                                                                         |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `systemPrompt`                                           | The agent's mission and constraints                                                  | [Prompt](/agents/prompt)                                                                           |
| `capabilities`                                           | Built-in LLM features (web search, memory, …)                                        | [Native LLM capabilities](/agents/native-llm-capabilities)                                         |
| `uses`                                                   | Everything it can invoke or read — tools, connector actions, sub-agents, data models | [Tools & actions](/agents/tools-and-actions), [Resources & context](/agents/resources-and-context) |
| `connector` / `languageModel` / `maxSteps` / `evaluator` | LLM provider and behavior                                                            | [Advanced settings](/agents/advanced)                                                              |

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

```bash theme={null}
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](/mcp-servers/overview) to expose them to external assistants.

## Using the UI

Prefer to build visually? See [Using the UI](/agents/using-ui) for the Instructions / Actions / Resources walkthrough. Agents built in code and in the UI are interchangeable.