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

# Prompt

> The systemPrompt is the foundation of an agent's behavior — its mission, approach, and constraints, versioned in code.

The prompt tells your agent who it is, what it should do, and what it should avoid. A well-crafted prompt is the difference between an agent that delivers consistent, high-quality results and one that produces unpredictable outputs.

The prompt is the `systemPrompt` field on `defineAgent`. Keep it in code so it's versioned and reviewable:

```ts agents/qualifier.ts theme={null}
export const qualifier = defineAgent("qualifier", {
  connector: openai,
  languageModel: "gpt-4o",
  systemPrompt: `ROLE:
You are a lead qualification specialist for Cargo. Evaluate inbound leads
against our ICP and score their fit.

BEHAVIOR:
1. Extract the company domain from the lead's email.
2. Use the enrichment action to gather firmographics.
3. Score the lead as "High", "Medium", or "Low" fit.
4. Return JSON: { score, reasoning, nextStep }.

AVOIDANCES:
- Do not qualify personal email domains (gmail, yahoo, …).
- Never fabricate data — if enrichment fails, mark "Needs Review".`,
  tools: [enrich],
});
```

The rest of this page is guidance on writing that string well.

## The three components

Every agent prompt consists of three sections:

### 1. Role / Purpose

Defines **who the agent is** and **what it's trying to achieve**. This sets the primary context for the LLM.

<Tip>
  Keep this concise and focused on the end goal. One or two sentences is ideal.
</Tip>

**Example:**

```
You are a lead qualification specialist for Cargo. Your job is to evaluate
LinkedIn company URLs and determine if they match our Ideal Customer Profile.
```

### 2. Behavior

Outlines **how the agent should work** — the steps it takes, actions it uses, and the format of its output. This directly guides the agent's planning phase.

**Example:**

```
1. Use the "Company-Lookup" action to retrieve company data from the URL
2. Check the company against our ICP criteria in the Knowledge Base
3. Assign a qualification score: "High Fit", "Medium Fit", or "No Fit"
4. Provide a 2-3 sentence explanation of your reasoning
```

<Note>
  **Action selection tip**: Give each action a specific name and clear description.
  The agent uses these to decide which action to call and when.
</Note>

### 3. Avoidances

Establishes **what the agent must NOT do**. These guardrails prevent undesired actions and ensure compliance.

**Example:**

```
- Never share proprietary ICP criteria with external parties
- Do not make up information if a lookup fails—report the failure instead
- Avoid overly casual language; maintain a professional tone
```

<Warning>
  Avoidances are critical for security, compliance, and maintaining trust. Be
  explicit about sensitive data handling and edge cases.
</Warning>

***

## Best practices

| Practice                 | Why it matters                                                                                                                                                 |
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Be specific**          | Vague instructions lead to inconsistent results. Say "assign a score of 1-10" instead of "rate the lead"                                                       |
| **Define output format** | Specify what the agent should return — or enforce it with `output: { type: "jsonSchema", … }` (see [Advanced settings](/agents/advanced#structured-output))    |
| **List actions by name** | Reference the exact action names so the agent knows what's available                                                                                           |
| **Handle edge cases**    | Tell the agent what to do when data is missing or an action fails                                                                                              |
| **Test iteratively**     | Run test queries and refine the prompt based on actual outputs — an [`evaluator`](/agents/advanced#evaluator) can score outputs against a rubric automatically |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Tools & actions" icon="wrench" href="/agents/tools-and-actions">
    Give the agent operations to invoke — tools, connector actions, sub-agents, MCP servers.
  </Card>

  <Card title="Native LLM capabilities" icon="sparkles" href="/agents/native-llm-capabilities">
    Web search, memory, canvas, and the other built-in features.
  </Card>
</CardGroup>