> ## 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 agent

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](/models/sweeps/initialize-sweeps) to explore different hyperparameter combinations. W\&B creates a new run for each hyperparameter combination the sweep agent tries.

See [Manage sweeps](/models/sweeps/pause-resume-and-cancel-sweeps) to learn how to pause, resume, stop, or cancel a sweep.

<Note>
  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](./add-w-and-b-to-your-code#training-script-with-w%26b-python-sdk).
  * Have a [configuration file](./define-sweep-configuration) defined for your sweep.
</Note>

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:

```bash theme={null}
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.

<Tabs>
  <Tab title="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:

    ```bash theme={null}
    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](/models/sweeps/signal-handling-sweep-runs) for details.
  </Tab>

  <Tab title="Python script or notebook">
    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 theme={null}
    wandb.agent(sweep_id="<sweep_id>", function="<function_name>")
    ```

    Signal forwarding from the agent to the training run is only supported when you use the CLI (`wandb agent --forward-signals`). It is not supported for `wandb.agent()` in Python because the training function runs in a thread, not as a child process. See [Signal handling and sweep runs](/models/sweeps/signal-handling-sweep-runs) for details.

    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.

    <Warning>
      **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 theme={null}
      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.
    </Warning>
  </Tab>
</Tabs>

### Limit the number of runs a sweep agent tries

<Warning>
  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).
</Warning>

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.

<Tabs>
  <Tab title="CLI">
    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.

    ```python theme={null}
    NUM=10
    SWEEPID="dtzl1o7u"
    wandb agent --count $NUM $SWEEPID
    ```
  </Tab>

  <Tab title="Python script or notebook">
    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.

    ```python theme={null}
    sweep_id, count = "dtzl1o7u", 10
    wandb.agent(sweep_id, count=count)
    ```

    <Warning>
      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.
    </Warning>
  </Tab>
</Tabs>