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:

agents/qualifier.ts

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".`,
  uses: [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.

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

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

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

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

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

---

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)
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 can score outputs against a rubric automatically

---

Next steps

Tools & actions

Give the agent operations to invoke — tools, connector actions, sub-agents, MCP servers.

Native LLM capabilities

Web search, memory, canvas, and the other built-in features.