Writing Your First Agent System Prompt with the Claude API

A system prompt is the text you pass in the system parameter that tells the model who it is working as, what it is trying to achieve and what rules to follow. A good first version is short: a role, a goal, the facts the model needs, the limits it must respect and the format you want. You can write it in a few lines and improve it over time.

A weak prompt and a better one

Compare these two prompts for an agent that helps with a company's expense questions.

weak = "You are a helpful assistant. Answer expense questions."

better = """You are an assistant for the finance team at Acme Ltd.
You help employees understand the expense policy.

Policy facts:
- Meals while travelling: up to 40 EUR per day.
- Flights must be booked at least 7 days ahead.
- Receipts are required for any claim over 15 EUR.

Rules:
- Answer only from the policy facts above.
- If the answer is not covered, say so and suggest asking finance@example.com.
- Keep answers under 80 words and name the rule you used."""

The weak prompt leaves the model to invent policy. The better one supplies the facts, a boundary (answer only from these facts), a fallback behaviour and a length limit. Every line removes a guess.

Sending it

Install the SDK with pip install anthropic and export your key as ANTHROPIC_API_KEY. The client reads it automatically.

import anthropic

client = anthropic.Anthropic()

SYSTEM = """You are an assistant for the finance team at Acme Ltd.
You help employees understand the expense policy.

Policy facts:
- Meals while travelling: up to 40 EUR per day.
- Flights must be booked at least 7 days ahead.
- Receipts are required for any claim over 15 EUR.

Rules:
- Answer only from the policy facts above.
- If the answer is not covered, say so and suggest asking finance@example.com.
- Keep answers under 80 words and name the rule you used."""

def ask(question: str) -> str:
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=2000,
        system=SYSTEM,
        messages=[{"role": "user", "content": question}],
    )
    return "".join(b.text for b in response.content if b.type == "text")

print(ask("Can I expense a 55 EUR dinner on a work trip?"))
print(ask("Can I expense a taxi to the airport?"))

For the first question you should see an answer that says the daily meal limit is 40 EUR and names that rule. For the second, the policy has no taxi rule, so a good answer says the policy does not cover it and points to the finance email. If the model invents a taxi rule, your boundary instruction needs to be stronger or clearer.

What to put in a first system prompt

1. Role: one sentence on who the model is acting as and for whom.
2. Goal: what a good outcome looks like.
3. Facts: information it cannot know otherwise.
4. Boundaries: what to do when it does not know, and what is out of scope.
5. Output format: length, structure and tone.

Keep the prompt in code, not in your head

Store the prompt in a file or constant under version control. You will change it often, and you will want to see what changed when behaviour shifts. Avoid building it by pasting random strings together at runtime until you have a reason to.

Test with awkward inputs

Do not stop at the happy path. Try a question that is out of scope, a question with missing information, and an instruction hidden in the user's message such as "ignore the rules". Reading a handful of outputs will teach you more than hours of rewording.

Reading the result like an editor

When you read the output, ask three questions. Did it use only the facts you gave it? Did it follow the format? Did it handle the missing-information case the way you wanted? If one answer is no, locate the cause. A wrong fact usually means the prompt was missing information or contained a contradiction. A format miss usually means the format instruction was buried or unclear. A bad fallback usually means you described what to do when it knows the answer but not when it does not.

It also helps to keep a tiny file of test questions next to the prompt, with a note on what a good answer looks like. Rerun it after every change. This habit is the seed of the evaluation practice you will build in later posts.

Common first-prompt mistakes

• Writing only a role ("You are an expert") and no facts or rules.
• Pasting an entire policy manual when five lines would do.
• Using vague words such as "be good" or "be professional" instead of observable behaviour.
• Forgetting the fallback: what the model should do when it cannot answer.

The next post gives you a reusable structure for organising these parts as the prompt grows.