> ## 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 models, tools, sub-agents, and connector actions.

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

| 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) |
| `tools` / `connectorActions`                             | Operations the agent can invoke               | [Tools & actions](/agents/tools-and-actions)               |
| `models`                                                 | Structured data it can read/write             | [Resources & context](/agents/resources-and-context)       |
| `subAgents`                                              | Specialist agents it can delegate to          | this page                                                  |
| `connector` / `languageModel` / `maxSteps` / `evaluator` | LLM provider and behavior                     | [Advanced settings](/agents/advanced)                      |

`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

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