Skip to main content
System prompts define what your agent knows and how it behaves. AFK supports three methods — inline strings, instruction files, and auto-detection — with Jinja2 templating for dynamic values.

​
Three ways to set instructions

Set instructions directly on the Agent. Best for simple, static prompts.
agent = Agent(
    name="assistant",
    model="gpt-5.2-mini",
    instructions="You are a helpful assistant. Be concise and accurate.",
)

​
Precedence chain

When multiple sources are available, AFK uses this order: The first non-empty source wins. If you set both instructions and instruction_file, the inline string takes priority.

​
Template variables with Jinja2

Use {{ variable }} syntax to inject dynamic values into prompts: 
agent = Agent(
    name="support-agent",
    model="gpt-5.2-mini",
    instructions="""
    You are a support agent for {{ company_name }}.
    Today's date is {{ current_date }}.
    The customer's plan is {{ plan_tier }}.

    {% if plan_tier == "enterprise" %}
    You may offer extended SLAs and priority escalation.
    {% else %}
    Refer complex issues to the support team.
    {% endif %}
    """,
    context={
        "company_name": "Acme Corp",
        "current_date": "2025-01-15",
        "plan_tier": "enterprise",
    },
)

​
Available template variables

SourceVariablesExample
Agent.context dictAny key-value pairs you set{{ company_name }}, {{ user_role }}
Built-inagent_name, model_name{{ agent_name }}
Runtimerun_id, thread_id (if available){{ thread_id }}

​
Prompt from file with templates

Templates work in instruction files too: 
agent = Agent(
    name="reviewer",
    model="gpt-5.2-mini",
    instruction_file="prompts/reviewer.md",
    context={
        "language": "Python",
        "style_guide": "PEP 8",
        "max_issues": 10,
    },
)
prompts/reviewer.md
You are a {{ language }} code reviewer following {{ style_guide }}.

## Rules

- Report at most {{ max_issues }} issues per review
- Classify issues as: error, warning, style
- Suggest a fix for each issue
- Be constructive and specific

​
Error handling

ErrorCauseResolution
PromptResolutionErrorinstruction_file path doesn’t existCheck the file path. Make sure it’s relative to the working directory or absolute.
PromptTemplateErrorJinja2 template syntax errorCheck for unclosed {{ }} or {% %} blocks.
PromptTemplateErrorMissing template variableAdd the variable to Agent.context or provide a default: {{ var | default("fallback") }}
Keep prompts in version control. Store instruction files in a prompts/ directory and track changes in git. This gives you prompt history, diffs, and the ability to A/B test prompt versions.

​
Design guidelines

  • Inline for prototyping, files for production. Switch to instruction files when your prompt exceeds ~5 lines.
  • Use templates for anything dynamic. Don’t concatenate strings — use {{ variable }} and set values in context.
  • Be specific in instructions. Tell the agent what to do and what not to do. Include output format expectations.
  • Test prompt changes with evals. A small prompt change can dramatically shift behavior. Run your eval suite after any edit.

​
Next steps

Agent Skills

Reusable knowledge bundles loaded on demand.

Evals

Test prompt changes with behavioral assertions.