Implementation:CARLA simulator Carla BasicAgent Init

Knowledge Sources	CARLA Simulator CARLA Documentation
Domains	Autonomous Driving, Agent Architecture, Motion Planning
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for initializing autonomous navigation agents provided by the CARLA simulator agents library. The BasicAgent and BehaviorAgent constructors wire together the global route planner, local planner, PID controller, and perception subsystems into a ready-to-use driving agent.

Description

BasicAgent.__init__ creates an agent bound to a specific CARLA vehicle actor. It:

1. Retrieves the CARLA world handle and map from the vehicle's parent world
2. Instantiates a LocalPlanner with PID controller gains and a target speed
3. Instantiates a GlobalRoutePlanner (or reuses one passed via grp_inst) with configurable sampling resolution
4. Sets default perception parameters: ignore_traffic_lights, ignore_stop_signs, ignore_vehicles flags, proximity thresholds for vehicles (10 m), traffic lights (10 m), and walkers (5 m)
5. Merges any user-supplied overrides from the opt_dict dictionary

BehaviorAgent.__init__ extends this by:

1. Calling the parent BasicAgent.__init__
2. Loading a behavior profile (Cautious, Normal, or Aggressive) that defines speed_lim_dist, safety_time, min_proximity_threshold, and speed_decrease parameters
3. Storing a reference to a look-ahead waypoint for intersection decisions

Usage

Use BasicAgent when you need a simple, rule-based autonomous agent that follows lanes, obeys traffic lights, and stops for obstacles. Use BehaviorAgent when you want personality-driven driving with tailgating, car-following, and speed adaptation.

Code Reference

Source Location

• Repository: CARLA
• File: PythonAPI/carla/agents/navigation/basic_agent.py
• Lines: L30-104
• File: PythonAPI/carla/agents/navigation/behavior_agent.py
• Lines: L33-63

Signature

class BasicAgent(object):
    def __init__(self, vehicle, target_speed=20, opt_dict={}, map_inst=None, grp_inst=None):
        ...

class BehaviorAgent(BasicAgent):
    def __init__(self, vehicle, behavior='normal', opt_dict={}, map_inst=None, grp_inst=None):
        ...

Import

from agents.navigation.basic_agent import BasicAgent
from agents.navigation.behavior_agent import BehaviorAgent

I/O Contract

Inputs

Name	Type	Required	Description
vehicle	carla.Vehicle	Yes	The CARLA vehicle actor this agent will control
target_speed	float	No (default: 20)	Desired cruising speed in km/h
opt_dict	dict	No (default: {})	Dictionary of overrides for agent parameters (e.g., 'target_speed', 'ignore_traffic_lights', 'sampling_resolution', 'base_vehicle_threshold', PID gains)
map_inst	carla.Map	No (default: None)	Pre-loaded map instance; if None, retrieved from the world
grp_inst	GlobalRoutePlanner	No (default: None)	Pre-built global route planner; if None, a new one is created
behavior	str	No (default: 'normal')	BehaviorAgent only: one of 'cautious', 'normal', or 'aggressive'

Outputs

Name	Type	Description
(instance)	BasicAgent or BehaviorAgent	A fully initialized navigation agent ready for set_destination() and run_step() calls

Usage Examples

Basic Example

import carla
from agents.navigation.basic_agent import BasicAgent

# Connect to CARLA and spawn a vehicle
client = carla.Client('localhost', 2000)
world = client.get_world()
blueprint = world.get_blueprint_library().find('vehicle.tesla.model3')
spawn_point = world.get_map().get_spawn_points()[0]
vehicle = world.spawn_actor(blueprint, spawn_point)

# Initialize BasicAgent with custom target speed
agent = BasicAgent(vehicle, target_speed=30)

# Set a destination and run the navigation loop
destination = world.get_map().get_spawn_points()[50].location
agent.set_destination(destination)

while True:
    if agent.done():
        print("Destination reached.")
        break
    control = agent.run_step()
    vehicle.apply_control(control)
    world.tick()

BehaviorAgent Example

from agents.navigation.behavior_agent import BehaviorAgent

# Initialize a cautious BehaviorAgent
agent = BehaviorAgent(vehicle, behavior='cautious', opt_dict={'target_speed': 25})

# Set destination and run
agent.set_destination(destination)
while not agent.done():
    control = agent.run_step()
    vehicle.apply_control(control)
    world.tick()

Related Pages

Implements Principle

• Principle:CARLA_simulator_Carla_Navigation_Agent_Architecture

Requires Environment

• Environment:CARLA_simulator_Carla_Python_API_Runtime