Prompt Engineering

Prompt Engineering for AI Agents

Prompt quality is the single biggest lever for agent reliability. Learn the anatomy of effective prompts and the techniques used inside OpenClaw to write prompts that work consistently.

Why Prompts Matter More in Agents

In a chatbot, a weak prompt means a mediocre reply. In an agent, a weak prompt can cause wrong tools to be called, incorrect output formats, or endless loops. Agents execute multi-step workflows where each step amplifies upstream prompt errors.

ContextImpact of a poor prompt
ChatbotVague or off-topic answer
Agent (tool selection)Wrong tool chosen → wrong action taken
Agent (multi-step)Early error cascades through all downstream steps
Agent (pipeline)One agent passes garbage to the next; whole run fails

Anatomy of an Effective Prompt

Every high-quality agent prompt shares five elements:

  1. Role — Who the agent is. "You are a senior data analyst …"
  2. Context — The situation. "The user has uploaded a CSV …"
  3. Task — The specific goal. "Identify the three largest outliers …"
  4. Constraints — Guardrails. "Respond only with JSON. Never include PII."
  5. Output format — Exact schema. "Return {"outliers": [...]}"

OpenClaw Prompt Layers

OpenClaw assembles four layers into the final prompt sent to the LLM:

  1. System prompt — Agent persona, global constraints, output format.
  2. Task description — The goal for this specific run.
  3. Memory — Relevant past conversation or retrieved context.
  4. Tool context — Available tools with type signatures injected automatically.
# In openclaw.yaml
agents:
  - name: analyst
    system_prompt: |
      You are a data analyst. Return only JSON.
    tools: [read_csv, run_python]

5 Prompt Improvements That Work Immediately

  1. Add an explicit output format — "Respond with a JSON object: {"summary": "", "tags": []}"
  2. Give the agent a role — "You are an expert Python developer with 10 years experience."
  3. Use numbered steps — Forces sequential reasoning instead of stream-of-consciousness.
  4. Add "think before answering" — "Before responding, briefly reason through the problem."
  5. Be explicit about edge cases — "If no data is found, return {"error": "not_found"}."

Prompt Iteration Workflow

  1. Write a baseline prompt and collect 10 sample outputs.
  2. Identify the most common failure modes.
  3. Fix the highest-impact issue only (one change at a time).
  4. Re-run on the same samples to measure improvement.
  5. Repeat until acceptable quality.
  6. Freeze the prompt in version control.

Prompt Lifecycle Management

A prompt is born in a notebook, graduates to a YAML file, earns automated tests, and eventually gets versioned like a library. Following this lifecycle prevents the most common failure mode: a well-intentioned prompt edit silently breaking production behaviour weeks later.

StageActivityTooling
ExplorationWrite and iterate manually in a Jupyter notebook or playgroundOpenAI Playground, LangSmith
FormalisationMove to a versioned YAML promptbook with named variablesGit, Jinja2
TestingAdd regression tests; add to CI pipelinepytest, GitHub Actions
OptimisationToken compression, model downgrade testing, cachingtiktoken, benchmarks
MonitoringTrack token cost and quality metrics in productionOpenClaw metrics, Prometheus
RetirementDeprecate when task changes or model capabilities advanceChangelog entry, redirect to new prompt

Debugging Prompts

When an agent produces unexpected output, start with the prompt, not the code. These techniques narrow down the root cause quickly:

  • Print the full constructed prompt. Dynamic prompts often contain stale context, missing variables, or injected content you didn’t expect. Always log (or print) the exact prompt sent, not the template.
  • Isolate variable contributions. Re-run with each dynamic variable replaced by a known constant. If the problem disappears, that variable is the culprit.
  • Try zero-shot first. Remove examples, context, and formatting instructions. If the bare instruction works, add components back one at a time until the problem re-emerges.
  • Test across multiple samples. A single run can succeed by chance. Run 5–20 samples to distinguish a systematic problem from random variation.
  • Change model as a diagnostic. If GPT-4o succeeds but GPT-4o-mini fails, the prompt is relying on capabilities not available in smaller models — add more examples or restructure instructions.

Prompt Review Checklist

Use this checklist before promoting any new prompt to production:

  • ✅ Does the prompt include a clear role/persona?
  • ✅ Are output format requirements explicit (JSON, markdown, plain text)?
  • ✅ Is the prompt tested with at least 3 diverse inputs?
  • ✅ Does it handle the failure / edge case (empty input, long input, adversarial input)?
  • ✅ Is the token count under the target budget?
  • ✅ Has it been reviewed by a second person for unintended instruction conflicts?
  • ✅ Is it stored in version control with a changelog entry?
  • ✅ Are CI regression tests passing?