Start a sweep agent

Start or stop a W&B Sweep Agent on one or more machines.

Start a sweep on one or more agents on one or more machines. Sweep agents use the sweep configuration defined when you initialize a sweep to explore different hyperparameter combinations. W&B creates a new run for each hyperparameter combination the sweep agent tries.

See Manage sweeps to learn how to pause, resume, stop, or cancel a sweep.

Before you continue, make sure you:

• Configure your training script to create and track hyperparameter combinations with W&B. For more information, see Add W&B to your code.
• Have a configuration file defined for your sweep.

The following code snippets demonstrate how to start an agent with the CLI and within a Jupyter Notebook or Python script. For both methods, provide the sweep ID that W&B returns when you initialized the sweep. The sweep ID has the form:

entity/project/sweep_ID

Where:

• entity: Your W&B username or team name.
• project: The name of the project where you want W&B to store the output of the run. If the project is not specified, W&B puts the run in a project called “Uncategorized”.
• sweep_ID: The pseudo random, unique ID generated by W&B.

CLI

Use the wandb agent command to start a sweep. Provide the sweep ID that W&B returns when you initialized the sweep.

Copy and paste the code snippet below and replace sweep_id with your sweep ID:

wandb agent sweep_id

For graceful shutdown when you interrupt the agent (for example, with Ctrl+C), use wandb agent --forward-signals sweep_id so the current run receives the signal and can shut down cleanly. See Signal handling and sweep runs for details.

Python script or notebook

Use wandb.agent() to start a sweep. Provide the sweep ID that W&B returns when you initialized the sweep along with the name of the function that is the entrypoint to your training script.

Copy and paste the code snippet below and replace <sweep_id> with your sweep ID and <function_name> with the name of your training function:

wandb.agent(sweep_id="<sweep_id>", function="<function_name>")

To forward signals to the training run when you interrupt the agent (for example, Ctrl+C), pass forward_signals=True: wandb.agent(sweep_id="<sweep_id>", function="<function_name>", forward_signals=True). See Signal handling and sweep runs for details.

See Python script or notebook tab in Add W&B to your code for an example of how to set up your training script if you use this method.

Multiprocessing

You must wrap your wandb.agent() and wandb.sweep() calls with if __name__ == '__main__': if you use Python standard library’s multiprocessing or PyTorch’s pytorch.multiprocessing package. For example:

if __name__ == '__main__':
    wandb.agent(sweep_id="<sweep_id>", function="<function>", count="<count>")

Wrapping your code with this convention ensures that it is only executed when the script is run directly, and not when it is imported as a module in a worker process.

See Python standard library multiprocessing or PyTorch multiprocessing for more information about multiprocessing. See https://realpython.com/if-name-main-python/ for information about the if __name__ == '__main__': convention.

Limit the number of runs a sweep agent tries

Random and Bayesian searches will run forever. You must stop the process from the command line, within your python script, or the Sweeps UI.

Specify the number of runs a sweep agent should try. The following code snippets demonstrate how to set a maximum number of W&B Runs with the CLI and within a Jupyter Notebook, Python script.

CLI

First, initialize your sweep with the wandb sweep command. For more information, see Initialize sweeps.

wandb sweep config.yaml

Next, pass an integer value to the count flag to set the maximum number of runs to try.

NUM=10
SWEEPID="dtzl1o7u"
wandb agent --count $NUM $SWEEPID

Python script or notebook

First, initialize your sweep. For more information, see Initialize sweeps.

sweep_id = wandb.sweep(sweep_config)

Next, start the sweep job. Provide the sweep ID generated from sweep initiation. Pass an integer value to the count parameter to set the maximum number of runs to try.

sweep_id, count = "dtzl1o7u", 10
wandb.agent(sweep_id, count=count)

If you start a new run after the sweep agent has finished, within the same script or notebook, then you should call wandb.teardown() before starting the new run.