Save the date! Google I/O returns May 18-20 Register now

tf_agents.agents.BehavioralCloningAgent

A Behavioral Cloning agent.

Inherits From: TFAgent

tf_agents.agents.BehavioralCloningAgent(
    time_step_spec: tf_agents.trajectories.time_step.TimeStep,
    action_spec: tf_agents.typing.types.NestedTensorSpec,
    cloning_network: tf_agents.networks.Network,
    optimizer: tf_agents.typing.types.Optimizer,
    num_outer_dims: Literal[1, 2] = 1,
    epsilon_greedy: tf_agents.typing.types.Float = 0.1,
    loss_fn: Callable[[tf_agents.typing.types.Tnest], tf_agents.typing.types.Tensor] = None,
    gradient_clipping: Optional[types.Float] = None,
    debug_summaries: bool = False,
    summarize_grads_and_vars: bool = False,
    train_step_counter: Optional[tf.Variable] = None,
    name: Optional[Text] = None
)

Implements a generic form of BehavioralCloning that can also be used to pipe supervised learning through TF-Agents. By default the agent defines two types of losses.

For discrete actions the agent uses:

def discrete_loss(agent, experience):
  bc_logits = self._cloning_network(experience.observation)

  return tf.nn.sparse_softmax_cross_entropy_with_logits(
    labels=experience.action - action_spec.minimum, logits=bc_logits)

This requires a Network that generates num_action Q-values. In the case of continuous actions a simple MSE loss is used by default:

def continuous_loss_fn(agent, experience):
  bc_output, _ = self._cloning_network(
      experience.observation,
      step_type=experience.step_type,
      training=True,
      network_state=network_state)

  if isinstance(bc_output, tfp.distributions.Distribution):
    bc_action = bc_output.sample()
  else:
    bc_action = bc_output

  return tf.losses.mse(experience.action, bc_action)

The implementation of these loss functions is slightly more complex to support nested action_specs.

time_step_spec A TimeStep spec of the expected time_steps.
action_spec A nest of BoundedTensorSpec representing the actions.
cloning_network A tf_agents.networks.Network to be used by the agent. The network will be called as

network(observation, step_type=step_type, network_state=initial_state)

and must return a 2-tuple with elements (output, next_network_state)

optimizer The optimizer to use for training.
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.
epsilon_greedy probability of choosing a random action in the default epsilon-greedy collect policy (used only if actions are discrete)
loss_fn A function for computing the error between the output of the cloning network and the action that was taken. If None, the loss depends on the action dtype. The loss_fn is called with parameters: agent, experience, and must return a loss value for each element of the batch.
gradient_clipping Norm length to clip gradients.
debug_summaries A bool to gather debug summaries.
summarize_grads_and_vars If True, gradient and network variable summaries will be written during training.
train_step_counter An optional counter to increment every time the train op is run. Defaults to the global_step.
name The name of this agent. All variables in this module will fall under that name. Defaults to the class name.

action_spec TensorSpec describing the action produced by the agent.
cloning_network

collect_data_context

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.
data_context

debug_summaries

policy Return the current policy held by the agent.
summaries_enabled

summarize_grads_and_vars

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.

train_step_counter

training_data_spec Returns a trajectory spec, as expected by the train() function.
validate_args Whether train & preprocess_sequence validate input & output args.

Methods

initialize

View source

initialize() -> Optional[tf.Operation]

Initializes the agent.

Returns
An operation that can be used to initialize the agent.

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

loss

View source

loss(
    experience: tf_agents.typing.types.NestedTensor,
    weights: Optional[types.Tensor] = None,
    **kwargs
) -> tf_agents.agents.tf_agent.LossInfo

Gets loss from the agent.

If the user calls this from _train, it must be in a tf.GradientTape scope in order to apply gradients to trainable variables. If intermediate gradient steps are needed, _loss and _train will return different values since _loss only supports updating all gradients at once after all losses have been calculated.

Args
experience A batch of experience data in the form of a Trajectory. The structure of experience must match that of self.training_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 args to loss.

Returns
A LossInfo loss tuple containing loss and info tensors.

Raises
TypeError If validate_args is True and: Experience is not type Trajectory; or if experience does not match self.training_data_spec structure types.
ValueError If validate_args is True and: Experience tensors' time axes are not compatible with self.train_sequence_length; or if experience does not match self.training_data_spec structure.
ValueError If validate_args is True and the user does not pass **kwargs matching self.train_argspec.
RuntimeError If the class was not initialized properly (super.__init__ was not called).

preprocess_sequence

View source

preprocess_sequence(
    experience: tf_agents.typing.types.NestedTensor
) -> tf_agents.typing.types.NestedTensor

Defines preprocess_sequence function to be fed into replay buffers.

This defines how we preprocess the collected data before training. Defaults to pass through for most agents. Structure of experience must match that of self.collect_data_spec.

Args
experience a Trajectory shaped [batch, time, ...] or [time, ...] which represents the collected experience data.

Returns
A post processed Trajectory with the same shape as the input.

Raises
TypeError If experience does not match self.collect_data_spec structure types.

train

View source

train(
    experience: tf_agents.typing.types.NestedTensor,
    weights: Optional[types.Tensor] = None,
    **kwargs
) -> tf_agents.agents.tf_agent.LossInfo

Trains the agent.

Args
experience A batch of experience data in the form of a Trajectory. The structure of experience must match that of self.training_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.

Returns
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.

Raises
TypeError If validate_args is True and: Experience is not type Trajectory; or if experience does not match self.training_data_spec structure types.
ValueError If validate_args is True and: Experience tensors' time axes are not compatible with self.train_sequence_length; or if experience does not match self.training_data_spec structure.
ValueError If validate_args is True and the user does not pass **kwargs matching self.train_argspec.
RuntimeError If the class was not initialized properly (super.__init__ was not called).