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

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Advanced settings

> LLM selection, behavioral tuning, structured output, evaluators, triggers, and heartbeats — everything else on defineAgent.

Beyond the prompt and actions, `defineAgent` carries the agent's LLM binding and its behavioral settings:

```ts agents/qualifier.ts theme={null}
export const qualifier = defineAgent("qualifier", {
  connector: openai, // the LLM provider connector
  languageModel: "gpt-4o", // the model slug
  systemPrompt: "Qualify leads against our ICP.",
  temperature: 0.2, // 0.0–0.2 deterministic, 0.7+ creative (default 0.2)
  maxSteps: 4, // reasoning-step budget (default 8)
  withReasoning: false, // extended thinking before acting (default false)
  output: { type: "text" }, // or a jsonSchema contract — see below
  evaluator: { rubric: "Did it correctly qualify the lead?", threshold: 0.8 },
  triggers: [
    { type: "cron", cron: "0 9 * * *", text: "Qualify yesterday's leads" },
  ],
});
```

> [!NOTE]
>
> Every agent needs both `connector` and `languageModel` — `defineAgent`
> throws at `plan` time if either is missing. The connector's integration
> (OpenAI, Anthropic, …) determines which model slugs are valid. A harness
> only accepts connectors and models that list that runtime (Anthropic for
> Claude Code / OpenCode / Deep Agents, OpenAI gpt-5\* for Codex).

***

## Coding agents

A coding agent runs inside a sandbox with a cloned repository. Set `harness` to the runtime (`claudeCode`, `codex`, `openCode`, or `deepAgents`) and `repository` to control what the sandbox clones.

### Automatic repository binding

**Omit `repository`** and `plan`/`deploy` fill it from the checkout they run in — the `owner/name` of your git `origin`, the remote's default branch, and this project's path inside the repo — with the connector taken from the project's GitHub `defineConnector`:

```ts connectors/github.ts theme={null}
export const github = defineConnector("github", {
  integration: "github",
  default: true,
});
```

```ts connectors/anthropic.ts theme={null}
export const anthropic = defineConnector("anthropic", {
  integration: "anthropic",
});
```

```ts agents/coder.ts theme={null}
export const coder = defineAgent("coder", {
  harness: "claudeCode",
  connector: anthropic,
  languageModel: "claude-sonnet-5",
  systemPrompt: "Work on this repository.",
  // repository omitted → bound to this checkout's origin
});
```

Anything you declare wins, so a partial object is completed the same way and a full one is left alone. `plan` prints what it resolved (e.g. `agent:coder bound to acme/app#main in infra/`) and the resolved values are inside the content hash, so deploying the same code from a different repository is a real update.

### Edge cases

| Checkout | Behavior |
| :- | :- |
| **No GitHub remote** (GitLab origin, no origin, not a repo) | The agent stays unbound with an empty sandbox; `plan` says so |
| **GitHub remote but no GitHub connector** | An error — add one with `cargo-ai project add connector/github` |

### Opting out

Pass `repository: null` to force an unbound agent whatever the checkout says:

```ts theme={null}
export const coder = defineAgent("coder", {
  harness: "claudeCode",
  connector: anthropic,
  languageModel: "claude-sonnet-5",
  systemPrompt: "General coding assistant.",
  repository: null, // explicitly unbound
});
```

> [!WARNING]
>
> **Breaking change** — a harness agent that omits `repository` in a project
> that has a GitHub connector was previously deployed unbound. It now binds on
> the next plan. Use `repository: null` to keep the old behaviour.

***

## Selecting a model

The `connector` handle picks the provider; `languageModel` picks the model slug within it. Cargo supports the leading LLM providers — OpenAI, Anthropic, and Google Gemini among them — each behind its own [connector](https://docs.getcargo.ai/connectors/overview.md).

List the model slugs a provider currently exposes rather than hardcoding from memory:

```bash theme={null}
cargo-ai connection integration get openAi   # → available actions and model slugs
```

| Task profile | Recommended approach |
| :- | :- |
| **Complex analysis** (qualification, research synthesis) | The provider's most capable model |
| **Simple classification** (routing, tagging) | A fast, low-cost model |
| **High volume, low stakes** | Prioritize speed and cost |
| **Low volume, high stakes** | Prioritize reasoning quality |

> [!TIP]
>
> Start with a powerful model during development to understand what's possible,
> then optimize for cost/speed once the agent is working well.

***

## Behavioral parameters

### Reasoning steps (`maxSteps`)

The maximum number of logical sub-tasks the agent can perform to reach a conclusion. Defaults to `8`.

| Setting | Effect | Use when |
| :- | :- | :- |
| **Low (1-3)** | Fast, direct responses | Simple lookups, single-action tasks |
| **Medium (4-6)** | Balanced reasoning | Most standard workflows |
| **High (7+)** | Deep, multi-step problem solving | Complex research, multi-source synthesis |

> [!WARNING]
>
> Higher reasoning steps increase latency and cost. Only increase if the agent
> is failing to complete tasks.

### Temperature

Controls the creativity and variability of outputs. Defaults to `0.2`.

| Temperature | Behavior | Best for |
| :- | :- | :- |
| **0.0 - 0.2** | Deterministic, precise, consistent | Data extraction, classification, CRM updates |
| **0.3 - 0.6** | Balanced creativity | General tasks, qualification, research |
| **0.7 - 1.0** | Creative, varied | Copywriting, brainstorming, conversational engagement |

### Extended thinking (`withReasoning`)

`withReasoning: true` lets the model think through the problem before acting — better on hard multi-step tasks, at the cost of latency and tokens. Defaults to `false`.

***

## Structured output

By default an agent answers in free text (`output: { type: "text" }`). To make every final answer machine-parseable — for workflows or API consumers downstream — declare a JSON Schema contract:

```ts theme={null}
output: {
  type: "jsonSchema",
  jsonSchema: {
    type: "object",
    properties: {
      score: { type: "string", enum: ["High", "Medium", "Low"] },
      reasoning: { type: "string" },
    },
    required: ["score", "reasoning"],
  },
},
```

***

## Evaluator

The `evaluator` is an LLM-as-judge that scores each of the agent's outputs against a natural-language rubric:

```ts theme={null}
evaluator: {
  rubric: "Did it correctly qualify the lead, with evidence for the score?",
  threshold: 0.8,   // passing bar in [0, 1]
},
```

Outputs scoring below `threshold` are flagged, so you can spot quality regressions without reading every conversation. Pair it with prompt iterations: change the `systemPrompt`, re-deploy, and compare evaluator pass rates.

***

## Triggers

Agents normally respond to messages, but `triggers` make them start work on their own:

```ts theme={null}
triggers: [
  // On a schedule — `text` is the message the agent receives
  { type: "cron", cron: "0 9 * * *", text: "Qualify yesterday's inbound leads." },

  // On a connector event (e.g. an incoming Slack message)
  agentConnectorTrigger({ connector: slack, config: { channelIds: ["C0XXXX"] } }),
],
```

A `connector` trigger references its connector by handle or `connectorRef(uuid)`; `config` is integration-specific. `agentConnectorTrigger` types that `config` against the integration's schema, which a bare object literal can't do — TypeScript won't infer a per-element type through an array. A `defineConnector` handle names its integration, so the helper reads it from there; pass `integration: "slack"` yourself when there's no handle to read it from, either because you're using `connectorRef(uuid)` or because the trigger names an integration with no specific connector.

The bare form still works, with `config` left as a loose object:

```ts theme={null}
{ type: "connector", integration: "slack", connector: slack, config: { channelIds: ["C0XXXX"] } }
```

***

## Heartbeat

A `heartbeat` wakes the agent up on an interval inside an ongoing chat — useful for long-running missions that should make progress without a human prompting each turn:

```ts theme={null}
heartbeat: {
  intervalMinutes: 30,   // delay between heartbeat turns
  maxMessages: 40,       // stop waking up once the chat has this many messages
  prompt: null,          // message sent each turn; null = a generic "continue"
},
```

***

## Optimizing for cost and speed

Once your agent works correctly, consider:

1. **Reduce `maxSteps`** if tasks complete in fewer steps
2. **Try a faster model** and verify quality remains acceptable (the `evaluator` pass rate is the signal)
3. **Lower `temperature`** for more predictable outputs
4. **Limit resources** to reduce context size and processing time


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.