Traits, Templates, Codebooks, and Instructions

Traits Presentation Template

The traits presentation template controls how agent traits appear in LLM prompts.

Default Behavior

Without a template, traits are shown as a dictionary:

code

Your traits: {'age': 30, 'occupation': 'doctor'}

With a codebook but no custom template:

code

Your traits:
Age in years: 30
Current profession: doctor

Setting Custom Templates

Templates use Jinja2 syntax with access to trait values:

python

from edsl import Agent, AgentList

# For a single agent
agent = Agent(
    traits={"age": 30, "occupation": "doctor", "city": "Boston"},
    traits_presentation_template="You are a {{age}}-year-old {{occupation}} living in {{city}}."
)

# For all agents in a list (returns new AgentList)
agents = agents.set_traits_presentation_template(
    "You are a {{age}}-year-old {{occupation}} living in {{city}}."
)

Template Variables Available

Inside templates, you can reference:

•Individual trait keys: {{age}}, {{occupation}}
•The full traits dict: {{traits}}
•The codebook: {{codebook}}

python

# Example with codebook reference
template = """You are a person with these characteristics:
{% for key, value in traits.items() %}
- {{ codebook.get(key, key) }}: {{ value }}
{% endfor %}"""

agents = agents.set_traits_presentation_template(template)

Checking the Current Template

python

# View the template
print(agent.traits_presentation_template)

# View the rendered prompt with actual values
print(agent.prompt().text)

Codebooks

Codebooks map trait keys to human-readable descriptions.

For Individual Agents

python

from edsl import Agent

agent = Agent(
    traits={"age": 30, "occ": "MD"},
    codebook={"age": "Age in years", "occ": "Occupation code"}
)

For AgentLists (returns new AgentList)

python

# Set codebook for all agents
agents = agents.set_codebook({
    "age": "Age in years",
    "income": "Annual income in USD",
    "edu": "Highest education level"
})

# View current codebook
print(agents.codebook)

Instructions

Instructions guide how agents should answer questions.

For Individual Agents

python

agent = Agent(
    traits={"age": 30},
    instruction="Answer honestly based on your life experience."
)

For AgentLists (returns new AgentList)

python

# Using set_instruction
agents = agents.set_instruction("Answer as if you were this person.")

# Using add_instructions (alias)
agents = agents.add_instructions("Answer honestly and thoughtfully.")

# View current instruction
print(agents.instruction)

Dynamic Traits

Dynamic traits are computed at question-answering time:

python

from edsl import Agent

def dynamic_func(question):
    """Return different traits based on the question."""
    if "income" in question.question_text.lower():
        return {"disclosure_level": "private"}
    return {"disclosure_level": "public"}

agent = Agent(
    traits={"age": 30},
    dynamic_traits_function=dynamic_func
)

# Or set on existing agent
agent.dynamic_traits_function = dynamic_func

Dynamic Traits from Question Map

python

# Map questions to relevant traits
agents = agents.set_dynamic_traits_from_question_map({
    "hometown_question": ["hometown", "state"],
    "food_question": ["favorite_food", "dietary_restrictions"]
})

Quick Reference

Task	Single Agent	AgentList
Set codebook	`Agent(..., codebook={...})`	`agents.set_codebook({...})`
Set instruction	`Agent(..., instruction="...")`	`agents.set_instruction("...")`
Set template	`Agent(..., traits_presentation_template="...")`	`agents.set_traits_presentation_template("...")`
View codebook	`agent.codebook`	`agents.codebook`
View instruction	`agent.instruction`	`agents.instruction`
View template	`agent.traits_presentation_template`	`agents.traits_presentation_template`