> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-2751.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Start or stop a sweep agent on one or more machines.

# Start a sweep agent

This page explains how to start a sweep agent on one or more machines so that W\&B can run your hyperparameter search. Sweep agents use the sweep configuration that you define when you [initialize a sweep](/models/sweeps/initialize-sweeps) to explore different hyperparameter combinations. W\&B creates a new run for each hyperparameter combination that the sweep agent runs.

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

Before you continue:

* Configure your training script to create and track hyperparameter combinations with W\&B. See [Add W\&B to your code](/models/sweeps/add-w-and-b-to-your-code#python-script-or-notebook) for examples.
* Define a [configuration file](/models/sweeps/define-sweep-configuration) for your sweep.

These examples show how to start a sweep agent with the W\&B CLI or from Python. You need the sweep ID that W\&B returns when you initialize the sweep. You can use the short sweep ID on its own (for example, `dtzl1o7u`), or include the entity and project as a path:

```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 you don't specify the project, W\&B puts the run in a project called "Uncategorized".
* `sweep_ID`: The pseudo-random, unique ID that W\&B generates.

<Tabs>
  <Tab title="CLI">
    Use the `wandb agent` command to start a sweep. Provide the sweep ID that W\&B returns when you initialize the sweep.

    Replace `[SWEEP-ID]` with your sweep ID in the following command:

    ```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 initialize the sweep, along with the name of the function that serves as the entrypoint to your training script.

    Replace `[SWEEP-ID]` with your sweep ID and `[FUNCTION-NAME]` with the name of your training function in the following code:

    ```python theme={null}
    wandb.agent(sweep_id="[SWEEP-ID]", function="[FUNCTION-NAME]")
    ```

    W\&B only supports signal forwarding from the agent to the training run when you use the CLI (`wandb agent --forward-signals`). W\&B doesn't support signal forwarding for `wandb.agent()` in Python because the training function runs in a thread, not as a child process.

    See the [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 the 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 Python only runs it when you run the script directly, and not when a worker process imports it as a module.

      For more information about multiprocessing, 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 the `if __name__ == '__main__':` convention, see [Defining main functions in Python](https://realpython.com/if-name-main-python/).
    </Warning>
  </Tab>
</Tabs>

## Limit the number of runs a sweep agent tries

By default, random and Bayesian searches run indefinitely, so cap how many runs an agent attempts. Specify the number of runs a sweep agent should try to bound its work. The following code snippets demonstrate how to set a maximum number of [runs](/models/ref/python/experiments/run) with the CLI and within a Jupyter notebook or Python script.

<Warning>
  Random and Bayesian searches run indefinitely. If you don't set a run count, you must stop the process from the command line, from within your Python script, or from the [Sweeps UI](/models/sweeps/visualize-sweep-results).
</Warning>

<Tabs>
  <Tab title="CLI">
    First, initialize your sweep with the [`wandb sweep`](/models/ref/cli/wandb-sweep) command. For more information, see [Initialize sweeps](/models/sweeps/initialize-sweeps).

    ```bash theme={null}
    wandb sweep config.yaml
    ```

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

    ```bash 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](/models/sweeps/initialize-sweeps).

    ```python theme={null}
    sweep_id = wandb.sweep(sweep_config)
    ```

    Next, start the sweep job. Provide the sweep ID that sweep initiation generates. 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 finishes, within the same script or notebook, call `wandb.teardown()` before you start the new run.
    </Warning>
  </Tab>
</Tabs>