Skip to main content
Beyond the prompt and actions, defineAgent carries the agent’s LLM binding and its behavioral settings:
agents/qualifier.ts
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 clone of a project. Set harness to the runtime (claudeCode, codex, openCode, or deepAgents). state picks the project (deploy state) the sandbox clones: its state holds the repository, the project’s directory and its production branch.

Binding to this project

Omit state and plan/deploy fill in the state this project’s cargo.state.json points at. No GitHub connector is involved: the agent clones, pushes and opens pull requests as the Cargo GitHub app, so the project’s repository must be connected.
connectors/anthropic.ts
agents/coder.ts
plan prints the state it bound (e.g. agent:coder bound to this project's state <uuid>), and the uuid is inside the content hash, so pointing the project at another state redeploys its agents. Pass state: stateRef("<uuid>") to work on another project instead. env adds environment variables for the agent’s shell commands on top of the workspace’s, and runAs is the service user whose temporary CARGO_API_TOKEN the sandbox receives.

Edge cases

Breaking change — repository is gone from defineAgent: env and runAs move to the root, and the repository, branch and directory come from the project’s state. Remove repository (tsc flags it). A harness agent in a project works on a project: this one, or another named by stateRef. CDK before 1.0.150 sends repository and can no longer deploy agents: upgrade.

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. List the model slugs a provider currently exposes rather than hardcoding from memory:
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.
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.

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:

Evaluator

The evaluator is an LLM-as-judge that scores each of the agent’s outputs against a natural-language rubric:
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:
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. A project’s pull requests are the native agent state, declared with agentNativeTrigger({ agentSlug: "state", config }). It is named after the project, not the host: the project’s state chooses where its code lives, and the trigger means “this project’s pull requests” wherever that is. It takes no connector: on GitHub, events arrive from the Cargo GitHub app installed on the repository, and the agent answers as the app. Its config takes allPullRequests, fixFailedChecks, maxCheckFixAttempts, addressReviews and resolveConflicts. agentConnectorTrigger no longer accepts github, so tsc flags a project that still declares it that way: switch it to agentNativeTrigger. The bare form still works, with config left as a loose object:

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:

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