> ## Documentation Index
> Fetch the complete documentation index at: https://opentools.page/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run your first OpenTools toolset with OpenAI in minutes

OpenTools gives you ready-made toolsets (like Trading) that return consistent outputs.

In this quickstart, you’ll create a working agent that connects to your Alpaca account and returns your account information.

***

## Get started

<Steps titleSize="h2">
  <Step title="Install the SDK">
    <p>
      Open your terminal. We’re going to create a folder called <strong>my\_agent</strong>, set up a virtual
      environment, and install the minimal dependencies.
    </p>

    <CodeGroup>
      ```bash title="uv (recommended)" theme={null}
      mkdir my_agent
      cd my_agent
      uv venv
      uv pip install opentools-sdk openai python-dotenv
      ```

      ```bash title="pip" theme={null}
      mkdir my_agent
      cd my_agent
      python -m venv .venv
      source .venv/bin/activate
      pip install opentools-sdk openai python-dotenv
      ```
    </CodeGroup>

    <Tip>
      Use a virtual environment (<code>venv</code>) to ensure this demonstration is not affected by your other cool projects.
    </Tip>
  </Step>

  <Step title="Add your API keys to your .env file">
    <p>
      OpenTools reads credentials from environment variables. For this quickstart we’ll use{" "}
      <strong>Alpaca</strong> because of its strong capabilities and easy setup.
    </p>

    #### Model API key

    <Info>
      If you already have an <code>OpenAI API key</code>, just add it to your newly-created .env file.
    </Info>

    <ul>
      <li>Navigate to the OpenAI dashboard (API keys section)</li>
      <li>Click <strong>Create new secret key</strong></li>

      <li>
        Copy the key and store it somewhere safe (OpenAI recommends a secure place like your{" "}
        <code>.zshrc</code> but ensure to add it to your .env file)
      </li>
    </ul>

    <Note>
      In this demo we use a <code>.env</code> file and <code>python-dotenv</code>.\
      If you already export <code>OPENAI\_API\_KEY</code> globally, you can omit it from <code>.env</code>.
    </Note>

    #### Alpaca API key

    <Info>
      If you already have Alpaca keys, skip to the <code>.env</code> section below.
    </Info>

    <ul>
      <li>Create an Alpaca account (no funding required for paper trading)</li>
      <li>In the dashboard homepage, find <strong>Your API Keys</strong></li>
      <li>Click <strong>Generate New Keys</strong></li>

      <li>
        Copy:

        <ul>
          <li><strong>Key ID</strong></li>
          <li><strong>Secret Key</strong> (shown only once)</li>
        </ul>
      </li>
    </ul>

    <Warning>
      Alpaca only shows the <strong>Secret Key</strong> once. If you lose it, you must generate a new key pair.
    </Warning>

    #### Create a <code>.env</code> file

    <p>
      This quickstart uses <strong>paper trading</strong> by default and never places live trades unless you explicitly enable it. OpenTools does not store keys or manage OAuth. All credentials stay on your machine and are only used when tools are called.
    </p>

    <p>
      In the same folder as <code>main.py</code>, create a file named <code>.env</code>:
    </p>

    ```bash theme={null}
    OPENAI_API_KEY="your_openai_api_key"
    ALPACA_KEY="your_alpaca_key_id"
    ALPACA_SECRET="your_alpaca_secret_key"
    ```
  </Step>

  <Step title="Run your first tool call">
    <p>
      You’re about to run a small <strong>tool loop</strong>:
      the LLM decides which trading tool to call,
      OpenTools executes it, and the LLM summarises the result.
    </p>

    <Info>
      This example uses <strong>paper trading</strong> and <strong>minimal output</strong>.
      Nothing places orders unless you explicitly ask it to.
    </Info>

    #### Create a <code>main.py</code>

    <p>
      Create a file named <code>main.py</code> and paste the following code:
    </p>

    ```python theme={null}
    import asyncio
    import os

    from dotenv import load_dotenv
    from openai import AsyncOpenAI

    from opentools import trading
    from opentools.adapters.models.openai import run_with_tools


    async def main() -> None:
        # load OPENAI_API_KEY, ALPACA_KEY, ALPACA_SECRET from .env
        load_dotenv()

        # this quickstart uses no framework, just the model
        client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])

        # add the alpaca tools
        service = trading.alpaca(
            api_key=os.environ["ALPACA_KEY"],
            api_secret=os.environ["ALPACA_SECRET"],
            # specify the model, this is required for bundling tools correctly
            model="openai",
            # specify paper trading account or live trading account
            paper=True,
            # specify minimal output returned to model (maximum token efficiency)
            minimal=True,
        )

        prompt = "Show my account summary and list any open positions."

        # run_with_tools creates the tool-loop to make your development time quicker
        result = await run_with_tools(
            client=client,
            model="gpt-4.1-mini",
            service=service,
            user_prompt=prompt,
        )

        print(result)


    if __name__ == "__main__":
        asyncio.run(main())

    ```

    <p>
      The code above will add the tools automatically to the LLM context and use a loop to relay tool responses. The tools output structured schemas to ensure interpretability is maximised and relay the information accurately - this has been tested with LLMs as small as 7 billion parameters with clear, correct results.
    </p>

    #### Run your code

    <CodeGroup>
      ```bash title="uv" theme={null}
      uv run python main.py
      ```

      ```bash title="pip" theme={null}
      python main.py
      ```
    </CodeGroup>

    <p>
      If the model responds without calling tools, ensure you structure yours prompts directly around the tool,
      here are some examples: <code>"Get my account"</code>, <code>"List positions"</code>, or <code>"Show recent orders"</code>.
    </p>

    <Note>
      If you see a <code>KeyError</code>, one of your environment variables is missing
      or your <code>.env</code> file is not in the same directory as <code>main.py</code>.
    </Note>
  </Step>
</Steps>

***

## What just happened

<p>
  When you ran <code>main.py</code>, you gave the model a set of tool definitions from the <strong>Trading</strong> module. The model decided whether to call any tools. OpenTools executed those calls against Alpaca, then fed the results back to the model until it returned your final answer.
</p>

<p>
  This resulted in token-efficient output for <strong>your agent</strong> and guaranteed structure if calling the same tool again since intperpretability is standardised for model performance. Learn more about our capabilities and project structuring in the cards below.
</p>

<Columns cols={2}>
  <Card title="Modules" icon="boxes" href="/concepts/modules">
    Modules group tools under one domain and define what is normalised. **Trading** was used in this quickstart.
  </Card>

  <Card title="Models" icon="plug" href="/adapters/models">
    The Models adapter connects your LLM to the tool surface and runs your tool loop. <strong>Trading</strong> was used in this quickstart.
  </Card>
</Columns>

***

## Next steps

<p>
  This quickstart uses **OpenAI** directly. If you want a framework-managed agent loop, using PydanticAI for example,
  head to [Frameworks](/adapters/frameworks) or navigate by clicking on the card below.
</p>

<Card title="Frameworks" icon="plug" href="/adapters/frameworks">
  Frameworks provides a quick introduction to deploying established patterns that are supported by OpenTools, like PydanticAI.
</Card>