Updating agent traits

This notebook demonstrates how to update an agent’s traits with new answers to questions using the add traits() and to_agent_list() methods.

Learn more about designing and using AI agents with surveys in the documentation.

Updating a single agent

We start by creating an agent and using it with a survey:

[1]:
from edsl import Agent, QuestionFreeText, QuestionMultipleChoice, Survey
[2]:
agent = Agent(
    name = "college student",
    traits = {
        "persona": "You are a sophomore at a community college in upstate New York.",
        "year": "sophomore",
        "school": "community college",
        "major": "biology",
        "state": "New York"
    }
)
[3]:
q1 = QuestionFreeText(
    question_name = "career_interests",
    question_text = "What are your career interests?"
)

q2 = QuestionMultipleChoice(
    question_name = "attend_grad_school",
    question_text = "Do you plan to attend grad school?",
    question_options = ["Yes", "No", "Undecided"]
)

survey = Survey([q1, q2])
[4]:
results = survey.by(agent).run()
Job Status 🦜
Completed (1 completed, 0 failed)
Identifiers
Results UUID:
176e5a3f...90d5
Use Results.pull(uuid) to fetch results.
Job UUID:
4534fa5b...1880
Use Jobs.pull(uuid) to fetch job.
Status: Completed
Last updated: 2025-06-14 07:53:38
07:53:38
Job completed and Results stored on Coop. View Results
07:53:33
Job status: queued - last update: 2025-06-14 07:53:33 AM
07:53:33
View job progress here
07:53:33
Job details are available at your Coop account. Go to Remote Inference page
07:53:33
Job sent to server. (Job uuid=4534fa5b-4964-4acb-8fa9-f9f352d31880).
07:53:33
Your survey is running at the Expected Parrot server...
07:53:31
Remote inference activated. Sending job to server...
Model Costs ($0.0017 / 0.00 credits total)
Service Model Input Tokens Input Cost Output Tokens Output Cost Total Cost Total Credits
openai gpt-4o 216 $0.0006 108 $0.0011 $0.0017 0.00
Totals 216 $0.0006 108 $0.0011 $0.0017 0.00

You can obtain the total credit cost by multiplying the total USD cost by 100. A lower credit cost indicates that you saved money by retrieving responses from the universal remote cache.

[5]:
results.select("career_interests", "attend_grad_school")
[5]:
  answer.career_interests answer.attend_grad_school
0 I'm really interested in pursuing a career in the biological sciences. Since I'm majoring in biology, I'm exploring options like working in environmental conservation or possibly going into research. I'm also considering the healthcare field, as I've always been fascinated by how the human body works and how we can improve health outcomes. I still have some time to decide, so I'm keeping my options open while I learn more about each path. Undecided

Creating a new agent with original and new traits

Here we use the to_agent_list() method to create a new agent that has both the original traits and new traits for the survey responses:

[6]:
new_agent = results.select("persona", "year", "school", "major", "state", "career_interests", "attend_grad_school").to_agent_list()[0]
[7]:
type(new_agent)
[7]:
edsl.agents.agent.Agent
[8]:
new_agent
[8]:

Agent

  key value
0 traits:persona You are a sophomore at a community college in upstate New York.
1 traits:year sophomore
2 traits:school community college
3 traits:major biology
4 traits:state New York
5 traits:career_interests I'm really interested in pursuing a career in the biological sciences. Since I'm majoring in biology, I'm exploring options like working in environmental conservation or possibly going into research. I'm also considering the healthcare field, as I've always been fascinated by how the human body works and how we can improve health outcomes. I still have some time to decide, so I'm keeping my options open while I learn more about each path.
6 traits:attend_grad_school Undecided

Updating an existing agent

Here we use the add_traits() method to add the agent’s answers to its existing traits:

[9]:
career_interests = results.select("career_interests").to_list()[0] # there is only 1 answer
career_interests
[9]:
"I'm really interested in pursuing a career in the biological sciences. Since I'm majoring in biology, I'm exploring options like working in environmental conservation or possibly going into research. I'm also considering the healthcare field, as I've always been fascinated by how the human body works and how we can improve health outcomes. I still have some time to decide, so I'm keeping my options open while I learn more about each path."
[10]:
attend_grad_school = results.select("attend_grad_school").to_list()[0]
attend_grad_school
[10]:
'Undecided'
[11]:
agent.add_trait({
    "career_interests": career_interests,
    "attend_grad_school": attend_grad_school
})
agent
[11]:

Agent

  key value
0 traits:persona You are a sophomore at a community college in upstate New York.
1 traits:year sophomore
2 traits:school community college
3 traits:major biology
4 traits:state New York
5 name college student

Updating an agent list

Here we update a list of agents all at once:

[12]:
from edsl import AgentList
[13]:
agents = AgentList(
    Agent(traits = {"persona":p}) for p in ["School principal", "Nurse"]
)
[14]:
q1 = QuestionFreeText(
    question_name = "ideal_vacation",
    question_text = "Describe your ideal vacation."
)

q2 = QuestionMultipleChoice(
    question_name = "commute",
    question_text = "How do you typically commute to work?",
    question_options = ["Car", "Bus", "Train", "Bike", "Walk", "Other"]
)

survey = Survey([q1, q2])
[15]:
results = survey.by(agents).run()
Job Status 🦜
Completed (2 completed, 0 failed)
Identifiers
Results UUID:
ec2e8f9a...4bb1
Use Results.pull(uuid) to fetch results.
Job UUID:
6d6e9abd...f140
Use Jobs.pull(uuid) to fetch job.
Status: Completed
Last updated: 2025-06-14 07:53:48
07:53:48
Job completed and Results stored on Coop. View Results
07:53:43
Job status: queued - last update: 2025-06-14 07:53:43 AM
07:53:43
View job progress here
07:53:43
Job details are available at your Coop account. Go to Remote Inference page
07:53:43
Job sent to server. (Job uuid=6d6e9abd-a836-402f-8d8f-e7f94b1ef140).
07:53:43
Your survey is running at the Expected Parrot server...
07:53:42
Remote inference activated. Sending job to server...
Model Costs ($0.0038 / 0.00 credits total)
Service Model Input Tokens Input Cost Output Tokens Output Cost Total Cost Total Credits
openai gpt-4o 282 $0.0008 294 $0.0030 $0.0038 0.00
Totals 282 $0.0008 294 $0.0030 $0.0038 0.00

You can obtain the total credit cost by multiplying the total USD cost by 100. A lower credit cost indicates that you saved money by retrieving responses from the universal remote cache.

[16]:
results.select("persona", "ideal_vacation", "commute")
[16]:
  agent.persona answer.ideal_vacation answer.commute
0 School principal As a school principal, my ideal vacation would be a blend of relaxation and enrichment. I'd love to escape to a quiet coastal town where I can unwind with a good book, ideally something educational or related to leadership. Mornings would be for long walks on the beach, afternoons for exploring local museums or historical sites, and evenings for enjoying local cuisine. It would be a chance to recharge and gather new ideas to bring back to the school. A little time for reflection and planning for the upcoming school year would also be part of the itinerary. Car
1 Nurse As a nurse, my ideal vacation would be a mix of relaxation and adventure. I'd love to spend some time at a serene beach resort where I can unwind and soak up the sun, perhaps with a good book in hand. It's important to recharge and escape the hustle and bustle of a hospital environment. After a few days of relaxation, I'd enjoy exploring local culture and cuisine, perhaps visiting markets or taking a cooking class. A bit of hiking or a nature excursion would also be perfect to stay active and enjoy the beauty of nature. Overall, a balance of rest and exploration would make for a perfect getaway. Car
[17]:
new_agents = results.select("persona", "ideal_vacation", "commute").to_agent_list()
[18]:
type(new_agents)
[18]:
edsl.agents.agent_list.AgentList
[19]:
new_agents
[19]:

AgentList agents: 2;

  persona ideal_vacation commute
0 School principal As a school principal, my ideal vacation would be a blend of relaxation and enrichment. I'd love to escape to a quiet coastal town where I can unwind with a good book, ideally something educational or related to leadership. Mornings would be for long walks on the beach, afternoons for exploring local museums or historical sites, and evenings for enjoying local cuisine. It would be a chance to recharge and gather new ideas to bring back to the school. A little time for reflection and planning for the upcoming school year would also be part of the itinerary. Car
1 Nurse As a nurse, my ideal vacation would be a mix of relaxation and adventure. I'd love to spend some time at a serene beach resort where I can unwind and soak up the sun, perhaps with a good book in hand. It's important to recharge and escape the hustle and bustle of a hospital environment. After a few days of relaxation, I'd enjoy exploring local culture and cuisine, perhaps visiting markets or taking a cooking class. A bit of hiking or a nature excursion would also be perfect to stay active and enjoy the beauty of nature. Overall, a balance of rest and exploration would make for a perfect getaway. Car

Posting to Coop

Here we show how to post content to Coop, an integrated platform for creating and sharing AI research. Learn more about how it works.

[ ]:
from edsl import Notebook

nb = Notebook(path = "updating_agents.ipynb")

nb.push(
    description = "Updating agent traits with new answers",
    alias = "updating-agents-notebook",
    visibility = "public"
)