View source on GitHub

Abstract base class for TF RL agents.

time_step_spec A nest of tf.TypeSpec representing the time_steps. Provided by the user.
action_spec A nest of BoundedTensorSpec representing the actions. Provided by the user.
policy An instance of tf_policy.Base representing the Agent's current policy.
collect_policy An instance of tf_policy.Base representing the Agent's current data collection policy (used to set self.step_spec).
train_sequence_length A python integer or None, signifying the number of time steps required from tensors in experience as passed to train(). All tensors in experience will be shaped [B, T, ...] but for certain agents, T should be fixed. For example, DQN requires transitions in the form of 2 time steps, so for a non-RNN DQN Agent, set this value to 2. For agents that don't care, or which can handle T unknown at graph build time (i.e. most RNN-based agents), set this argument to None.
num_outer_dims The number of outer dimensions for the agent. Must be either 1 or 2. If 2, training will require both a batch_size and time dimension on every Tensor; if 1, training will require only a batch_size outer dimension.
train_argspec (Optional) Describes additional supported arguments to the train call. This must be a dict mapping strings to nests of specs. Overriding the experience arg is also supported.

Some algorithms require additional arguments to the train() call, and while TF-Agents encourages most of these to be provided in the policy_info / info field of experience, sometimes the extra information doesn't fit well, i.e., when it doesn't come from the policy.

Below is an example:

class MyAgent(TFAgent):
def __init__(self, counterfactual_training, ...):
collect_policy = ...
train_argspec = None
if counterfactual_training:
train_argspec = dict(

my_agent = MyAgent(...)

for ...:
experience, counterfactual = next(experience_and_counterfactual_iter)
loss_info = my_agent.train(experience, counterfactual=counterfactual)

debug_summaries A bool; if true, subclasses should gather debug summaries.
summarize_grads_and_vars A bool; if true, subclasses should additionally collect gradient and variable summaries.
enable_summaries A bool; if false, subclasses should not gather any summaries (debug or otherwise); subclasses should gate all summaries using either summaries_enabled, debug_summaries, or summarize_grads_and_vars properties.
train_step_counter An optional counter to increment every time the train op is run. Defaults to the global_step.

TypeError If train_argspec is not a dict.
ValueError If train_argspec has the keys experience or weights.
TypeError If any leaf nodes in train_argspec values are not subclasses of tf.TypeSpec.
ValueError If time_step_spec is not an instance of ts.TimeStep.
ValueError If num_outer_dims is not in [1, 2].

action_spec TensorSpec describing the action produced by the agent.
collect_data_spec Returns a Trajectory spec, as expected by the collect_policy.
collect_policy Return a policy that can be used to collect data from the environment.

name Returns the name of this module as passed or determined in the ctor.

name_scope Returns a tf.name_scope instance for this class.
policy Return the current policy held by the agent.
submodules Sequence of all sub-modules.

Submodules are modules which are properties of this module, or found as properties of modules which are properties of this module (and so on).

a = tf.Module()
b = tf.Module()
c = tf.Module()
a.b = b
b.c = c
list(a.submodules) == [b, c]
list(b.submodules) == [c]
list(c.submodules) == []



time_step_spec Describes the TimeStep tensors expected by the agent.
train_argspec TensorSpec describing extra supported kwargs to train().
train_sequence_length The number of time steps needed in experience tensors passed to train.

Train requires experience to be a Trajectory containing tensors shaped [B, T, ...]. This argument describes the value of T required.

For example, for non-RNN DQN training, T=2 because DQN requires single transitions.

If this value is None, then train can handle an unknown T (it can be determined at runtime from the data). Most RNN-based agents fall into this category.


trainable_variables Sequence of trainable variables owned by this module and its submodules.

variables Sequence of variables owned by this module and its submodules.



View source

Initializes the agent.

An operation that can be used to initialize the agent.

RuntimeError If the class was not initialized properly (super.__init__ was not called).


View source

Trains the agent.

experience A batch of experience data in the form of a Trajectory. The structure of experience must match that of self.collect_data_spec. All tensors in experience must be shaped [batch, time, ...] where time must be equal to self.train_step_length if that property is not None.
weights (optional). A Tensor, either 0-D or shaped [batch], containing weights to be used when calculating the total train loss. Weights are typically multiplied elementwise against the per-batch loss, but the implementation is up to the Agent.
**kwargs Any additional data as declared by self.train_argspec.

A LossInfo loss tuple containing loss and info tensors.

  • In eager mode, the loss values are first calculated, then a train step is performed before they are returned.
  • In graph mode, executing any or all of the loss tensors will first calculate the loss value(s), then perform a train step, and return the pre-train-step LossInfo.

TypeError If experience is not type Trajectory. Or if experience does not match self.collect_data_spec structure types.
ValueError If experience tensors' time axes are not compatible with self.train_sequence_length. Or if experience does not match self.collect_data_spec structure.
ValueError If the user does not pass **kwargs matching self.train_argspec.
RuntimeError If the class was not initialized properly (super.__init__ was not called).


Decorator to automatically enter the module name scope.

class MyModule(tf.Module):
  def __call__(self, x):
    if not hasattr(self, 'w'):
      self.w = tf.Variable(tf.random.normal([x.shape[1], 3]))
    return tf.matmul(x, self.w)

Using the above module would produce tf.Variables and tf.Tensors whose names included the module name:

mod = MyModule()
mod(tf.ones([1, 2]))
<tf.Tensor: shape=(1, 3), dtype=float32, numpy=..., dtype=float32)>
<tf.Variable 'my_module/Variable:0' shape=(2, 3) dtype=float32,
numpy=..., dtype=float32)>

method The method to wrap.

The original method wrapped such that it enters the module's name scope.