This module provides a set of basic agents:

Agent(object) base class for all other agents, implements the observe() method which receives an observation/action dict and the act() method which returns a dict in response.

Teacher(Agent) also implements the report() method for returning metrics. All ParlAI tasks implement the Teacher class.

MultiTaskTeacher(Teacher) creates a set of teachers based on a task string passed to the Teacher, creating multiple teachers within it and alternating between them.

All agents are initialized with the following parameters:

opt – contains any options needed to set up the agent. This generally contains all command-line arguments recognized from core.params, as well as other options that might be set through the framework to enable certain modes.

shared (optional) – if not None, contains any shared data used to construct this particular instantiation of the agent. This data might have been initialized by another agent, so that different agents can share the same data (possibly in different Processes).

This module also provides a utility method:

create_task_agents(str): instantiate task-specific agents (e.g. a teacher) from a given task string (e.g. ‘babi:task1k:1’ or ‘squad’). Used by MultiTaskTeacher.
class parlai.core.agents.Agent(opt, shared=None)

Base class for all other agents.


Receive an observation/action dict.


Return an observation/action dict based upon given observation.


If applicable, save any parameters needed to recreate this agent from loaded parameters.


If applicable, share any parameters needed to create a shared version of this agent.


Perform any final cleanup if needed.

class parlai.core.agents.Teacher(opt, shared=None)

Basic Teacher agent which keeps track of how many times it’s received messages. Teachers provide the report() method to get back metrics.


In addition to default Agent shared parameters, share metrics.

class parlai.core.agents.MultiTaskTeacher(opt, shared=None)

Creates a teacher that is actually a set of teachers each based on a task string–each of these teachers will get called in turn, either randomly or in order. They are all in the same world (they are the same agent switching tasks).

The task string format is described for the create_task_agents() function above.


Shutdown each agent.


Convert agent name to class.

This adds “Agent” to the end of the name and uppercases the first letter and the first letter appearing after each underscore (underscores are removed).

Parameters:name – name of agent, e.g. local_human

Returns class of agent, e.g. LocalHumanAgent.


Load agent options and module from file if opt file exists.

Checks to see if file exists opt[‘model_file’] + ”.opt”; if so, load up the options from the file and use that to create an agent, loading the model type from that file and overriding any options specified in that file when instantiating the agent.

If that file does not exist, return None.


Return the module for an agent specified by --model.

Can be formatted in several different ways:

  • full: -m parlai.agents.seq2seq.seq2seq:Seq2seqAgent
  • shorthand: -m seq2seq, which will check both paths parlai.agents.seq2seq.seq2seq:Seq2seqAgent and parlai.agents.seq2seq.agents:Seq2seqAgent
  • half-shorthand: -m seq2seq/variant, which will check the path parlai.agents.seq2seq.variant:VariantAgent
  • legacy models: -m legacy:seq2seq:0, which will look for the deprecated model at parlai.agents.legacy_agents.seq2seq.seq2seq_v0:Seq2seqAgent

The base path to search when using shorthand formats can be changed from “parlai” to “parlai_internal” by prepending “internal:” to the path, e.g. “internal:seq2seq”.

To use legacy agent versions, you can prepend “legacy:” to model arguments, e.g. “legacy:seq2seq:0” will translate to legacy_agents/seq2seq/seq2seq_v0.

Parameters:dir_name – path to model class in one of the above formats.
parlai.core.agents.create_agent(opt, requireModelExists=False)

Create an agent from the options model, model_params and model_file. The input is either of the form parlai.agents.ir_baseline.agents:IrBaselineAgent (i.e. the path followed by the class name) or else just ir_baseline which assumes the path above, and a class name suffixed with ‘Agent’.

If model-file is available in the options this function can also attempt to load the model from that location instead. This avoids having to specify all the other options necessary to set up the model including its name as they are all loaded from the options file if it exists (the file opt[‘model_file’] + ‘.opt’ must exist and contain a pickled or json dict containing the model’s options).


Instantiate an agent from the default shared params.

Parameters:shared_agent – should include an opt dictionary and agent class, along with whatever other parameters the agent needs to instantiate.

Create agents based on shared data.

Parameters:sharedlist of dict objects created by calling e.g. [a.share() for a in agents].

Returns a list of instantiated agents.


Get the module of the task agent specified by –task.

Can be formatted in several different ways:

  • full: -t parlai.tasks.babi.agents:DefaultTeacher
  • shorthand: -t babi, which will check
  • shorthand specific: -t babi:task10k, which will check

The base path to search when using shorthand formats can be changed from “parlai” to “parlai_internal” by prepending “internal:” to the path, e.g. “internal:babi”.

Options can be sent to the teacher by adding an additional colon, for example -t babi:task10k:1 directs the babi Task10kTeacher to use task number 1.

Parameters:taskname – path to task class in one of the above formats.
parlai.core.agents.add_task_flags_to_agent_opt(agent, opt, flags)

Allows to insert task flags in the task name itself, they are put inside the opt before the task is created.


Create task agent(s) assuming the input task_dir:teacher_class.

e.g. def_string is a shorthand path like babi:Task1k:1 or #babi or a complete path like parlai.tasks.babi.agents:Task1kTeacher:1, which essentially performs from parlai.tasks.babi import Task1kTeacher with the parameter 1 in opt['task'] to be used by the class Task1kTeacher.