Start a sweep agent ↗
noOriginal Documentation
Documentation Index#
Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt Use this file to discover all available pages before exploring further.
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_IDWhere:
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.
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
```
<span class="tab-end"></span>
<span class="tab-start" data-tab-title="Python script or notebook"></span>
Use [`wandb.agent()`](/models/ref/python/functions/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:
```python
wandb.agent(sweep_id="<sweep_id>", function="<function_name>")
```
See [Python script or notebook tab](/models/sweeps/add-w-and-b-to-your-code#python-script-or-notebook) in Add W\&B to your code for an example of how to set up your training script if you use this method.
<span class="callout-start" data-callout-type="warning"></span>
**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:
```python
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`](https://docs.python.org/3/library/multiprocessing.html#the-spawn-and-forkserver-start-methods) or [PyTorch `multiprocessing`](https://docs.pytorch.org/docs/stable/notes/multiprocessing.html#asynchronous-multiprocess-training-e-g-hogwild) for more information about multiprocessing. See [https://realpython.com/if-name-main-python/](https://realpython.com/if-name-main-python/) for information about the `if __name__ == '__main__':` convention.
<span class="callout-end"></span>
<span class="tab-end"></span>
<span class="tab-group-end"></span>
### Limit the number of runs a sweep agent tries
<span class="callout-start" data-callout-type="warning"></span>
Random and Bayesian searches will run forever. You must stop the process from the command line, within your python script, or the [Sweeps UI](./visualize-sweep-results).
<span class="callout-end"></span>
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](/models/ref/python/experiments/run) with the CLI and within a Jupyter Notebook, Python script.
<span class="tab-group-start"></span>
<span class="tab-start" data-tab-title="CLI"></span>
First, initialize your sweep with the [`wandb sweep`](/models/ref/cli/wandb-sweep) command. For more information, see [Initialize sweeps](./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
```
<span class="tab-end"></span>
<span class="tab-start" data-tab-title="Python script or notebook"></span>
First, initialize your sweep. For more information, see [Initialize sweeps](./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)
```
<span class="callout-start" data-callout-type="warning"></span>
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.
<span class="callout-end"></span>
<span class="tab-end"></span>
<span class="tab-group-end"></span>