Skip to main content
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".`,
  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.
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

PracticeWhy it matters
Be specificVague instructions lead to inconsistent results. Say “assign a score of 1-10” instead of “rate the lead”
Define output formatSpecify what the agent should return — or enforce it with output: { type: "jsonSchema", … } (see Advanced settings)
List actions by nameReference the exact action names so the agent knows what’s available
Handle edge casesTell the agent what to do when data is missing or an action fails
Test iterativelyRun 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.