***

id: f0f46679-2f87-463b-8dbd-903e463864b2
title: Quickstart
sidebar-title: Quickstart
subtitle: Python Agents SDK
slug: /python/guides/quickstart
keywords:

* SignalWire
* agents
* sdk
* ai
* python
  max-toc-depth: 3

***

Get up and running quickly with the SignalWire AI Agents SDK.
This section covers installation, basic setup, and your first AI agent implementation.

<div class="row">
  <div class="col col--6">
    ## Prerequisites

    * Python 3+
    * A SignalWire account
    * Ngrok (or other tunneling service)
    * `jq` (Optional but recommended)
  </div>

  <div class="col col--6">
    <Tip title="You don't need:">
      * **A credit card**: New SignalWire Spaces come with a \$5 starter credit
      * **Extensive Python or telecom knowledge**: This guide is beginner-friendly
    </Tip>
  </div>
</div>

<Steps>
  <Step title="Set up a virtual environment">
    Run this command in your desired project location.

    On macOS and some other Unix systems, use python3 for this step.
    With a venv active, "python" alone can be used.

    ```bash
    python -m venv .venv
    ```

    Next, run the activation script corresponding to your shell:

    <Tabs>
      <Tab title="bash/zsh">
        ```bash
        source .venv/bin/activate
        ```
      </Tab>

      <Tab title="fish">
        ```bash
        source .venv/bin/activate.fish
        ```
      </Tab>

      <Tab title="csh/tcsh">
        ```bash
        source .venv/bin/activate.csh
        ```
      </Tab>

      <Tab title="pwsh">
        ```bash
        .venv/bin/Activate.ps1
        ```
      </Tab>

      <Tab title="cmd.exe">
        ```bash
        .venv\Scripts\activate.bat
        ```
      </Tab>

      <Tab title="PowerShell">
        ```bash
        .venv\Scripts\Activate.ps1
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install the SDK">
    With a virtual environment activated,
    install the latest release of the Agents SDK and its dependencies.

    ```bash
    pip install signalwire-agents
    ```
  </Step>

  <Step title="Create your first agent">
    Create `dev-agent.py` and copy in the boilerplate below.

    <Tabs>
      <Tab title="Use AgentBase class">
        Notice that we are using the `AgentBase` class directly.
        This is appropriate for demos and simple applications using built-in skills and not needing custom business logic.

        ```python title="dev-agent.py"
        from signalwire_agents import AgentBase

        # Create an agent and assign a route
        agent = AgentBase("My Assistant", route="/assistant")

        # Add some basic capabilities
        agent.add_skill("datetime")     # Current date/time info
        agent.add_skill("math")         # Mathematical calculations

        # Start the agent
        agent.serve()
        ```
      </Tab>

      <Tab title="Create a custom class">
        For more advanced applications, create a custom class.

        ```python title="dev-agent.py"
        from signalwire_agents import AgentBase

        class TestAgent(AgentBase):

            def __init__(self, **kwargs):
                super().__init__(name="test", **kwargs)

        agent = TestAgent()

        # Add some basic capabilities
        agent.add_skill("datetime")     # Current date/time info
        agent.add_skill("math")         # Mathematical calculations

        # Start the agent
        agent.serve()
        ```
      </Tab>
    </Tabs>

    ***

    Done! It's literally that simple.
    We've created and named an agent, given it a route on our server,
    and taught it the `datetime` and `math` skills.
  </Step>

  <Step title="Serve the agent">
    Our boilerplate script above creates a new agent and assigns it a route on your server.
    To verify everything is working as it should,
    let's run the server locally.

    ```bash
    python dev-agent.py
    ```
  </Step>

  <Step title="Test the server">
    Great! The server should now be running on port 3000.
    Next, let's make an authenticated request to see the SWML generated by our boilerplate application.
    For now, we'll use the basic auth generated by the server.
    By default, the username is `signalwire`.
    Copy the generated password from the terminal on the line starting with `Basic Auth`.

    ```bash
    curl signalwire:password@0.0.0.0:3000/assistant
    ```

    You'll get back a payload of unstructured JSON.
    That's right, SWML is JSON!

    To read it more easily, pipe the result into `jq`, or open
    `0.0.0.0:3000/assistant`
    in the pretty print view available in most browsers.

    This basic SWML script is how the SignalWire cloud platform interacts with your application.
    When you configure a SignalWire phone number to call the application,
    SignalWire requests and processes SWML from your server.
  </Step>

  <Step title="Expose development server via tunnel">
    To let SignalWire make requests to your server running locally,
    we'll use Ngrok (or your tunneling service of choice) to expose port 3000.

    ```bash
    ngrok http 3000
    ```

    Verify that the tunneling is working with the same command as before.
    Replace `0.0.0.0` with your temporary hosted URL.
    You should get the same JSON response.

    ```bash
    curl https://signalwire:{{password}}@{{generated-url}}.ngrok-free.app:3000/assistant
    ```
  </Step>

  <Step title="Assign a phone number">
    We're almost done!
    The final step is to purchase and assign a phone number in your SignalWire Dashboard.
    In the Assign Resource menu, select **SWML Script**.
    Under **Primary Script**, set **Handle Calls Using** and select **External URL**.
    Here, paste the URL you just tested.

    ```bash
    https://signalwire:{{password}}@{{generated-url}}.ngrok-free.app:3000/assistant
    ```

    Lastly, click **Save**.
  </Step>

  <Step title="Try it out">
    With your application created, server running, tunnel live, and phone number configured,
    you can now call and talk to your brand-new Agent at its phone number.
  </Step>
</Steps>

## What's next?

Now that you have a basic agent running, explore these advanced topics:

* **[Configuration guide](/docs/agents-sdk/python/reference/configuration)**: Set up JSON configuration files and environment variable substitution
* **[Security guide](/docs/agents-sdk/python/guides/security)**: Configure HTTPS, authentication, and production security
* **[CLI tools](/docs/agents-sdk/python/reference/cli-swaig-test)**: Test and debug your agents with the command-line interface