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

# Quickstart

> Build your first agent with the Agentica SDK

This quickstart will guide you through building a simple chat agent that can use your tools.

<Steps>
  <Step title={<a href="#installation">Installation</a>}>
    Setup your project in `chat-with-tools`.
  </Step>

  <Step title={<a href="#build-an-agent">Get building</a>}>
    Build an agent with the Agentica SDK.
  </Step>
</Steps>

## Installation

We'll setup our project in a new directory called `chat-with-tools`.

<Tip>
  Get your API key from the [login page](https://www.symbolica.ai/login).
</Tip>

<Tabs>
  <Tab title="Python+uv">
    **Prerequisites:**

    * Python version `3.12.*`
    * `uv` package manager
    * Your Agentica Platform API key from the [login page](https://www.symbolica.ai/login)

    **Setup your virtual environment**

    ```bash theme={null}
    uv init chat-with-tools --python '==3.12.*'
    cd chat-with-tools
    uv sync
    source .venv/bin/activate
    uv add symbolica-agentica
    ```

    Export your API key under the `AGENTICA_API_KEY` environment variable.

    ```bash theme={null}
    export AGENTICA_API_KEY="your-key-here"
    ```

    Then, start editing your `main.py` file.
  </Tab>

  <Tab title="Python+pip">
    **Prerequisites:**

    * Python version `3.12.*`
    * `pip` package manager
    * Your Agentica Platform API key from the [login page](https://www.symbolica.ai/login)

    Check your Python version.

    ```bash theme={null}
    python --version
    # should be ~3.12.x
    ```

    **Setup your virtual environment**

    ```bash theme={null}
    mkdir chat-with-tools
    cd chat-with-tools
    python -m venv .venv
    source .venv/bin/activate
    pip install symbolica-agentica
    ```

    Export your API key under the `AGENTICA_API_KEY` environment variable.

    ```bash theme={null}
    export AGENTICA_API_KEY="your-key-here"
    ```

    Then, start editing your `main.py` file.
  </Tab>

  <Tab title="TypeScript+Node">
    **Prerequisites:**

    * Node.js version `>=20.0.0`
    * `npm` or `pnpm` package manager
    * Your Agentica Platform API key from the [login page](https://www.symbolica.ai/login)

    ```bash theme={null}
    node --version
    # should be >=20.0.0
    ```

    **Create your project**

    <CodeGroup>
      ```bash pnpm theme={null}
      mkdir chat-with-tools
      cd chat-with-tools
      pnpm init
      pnpm add -D typescript
      pnpm exec tsc --init
      pnpm add @symbolica/agentica
      pnpm exec agentica-setup
      pnpm install
      ```

      ```bash npm theme={null}
      mkdir chat-with-tools
      cd chat-with-tools
      npm init -y
      npm add -D typescript
      npx tsc --init
      npm add @symbolica/agentica
      npx agentica-setup
      npm install
      ```
    </CodeGroup>

    Edit your `package.json` file and add the following script:

    <CodeGroup>
      ```json pnpm theme={null}
      "scripts": {
        "build": "tspc src/index.ts", // [!code ++]
        "main": "pnpm run build && node src/index.js" // [!code ++]
      }
      ```

      ```json npm theme={null}
      "scripts": {
        "build": "tspc src/index.ts", // [!code ++]
        "main": "npm run build && node src/index.js" // [!code ++]
      }
      ```
    </CodeGroup>

    **Set your API key**

    ```bash theme={null}
    export AGENTICA_API_KEY="your-key-here"
    ```

    Then, start editing your `src/index.ts` file.
  </Tab>

  <Tab title="TypeScript+Bun">
    **Prerequisites:**

    * Bun runtime
    * Your Agentica Platform API key from the [login page](https://www.symbolica.ai/login)

    **Create your project**

    ```bash theme={null}
    mkdir chat-with-tools
    cd chat-with-tools
    bun init
    bun add @symbolica/agentica
    bunx agentica-setup
    ```

    During setup, choose "Bun plugin" as the build tool.

    **Set your API key**

    ```bash theme={null}
    export AGENTICA_API_KEY="your-key-here"
    ```

    Then, start editing your `src/index.ts` file.
  </Tab>
</Tabs>

## Your First Agent

<Tabs>
  <Tab title="Python">
    ```python wrap main.py theme={null}
    import asyncio
    from agentica import spawn
    from agentica.logging import set_default_agent_listener
    from agentica.logging.loggers import StreamLogger

    set_default_agent_listener(None)

    # Define your tools here!
    def my_tool(arg: str) -> str:
        """Describe what your tool does."""
        return f"Result for: {arg}"

    async def main():
        agent = await spawn(premise="You are a helpful assistant.")

        print("Agent ready! Type 'quit' to exit.\n")

        while True:
            user_input = input("You: ")
            if user_input.lower() == "quit":
                break

            # Stream the agent's response
            stream = StreamLogger()
            with stream:
                result = asyncio.create_task(
                    agent.call(str, user_input, my_tool=my_tool)  # Pass your tools here
                )

            async for chunk in stream:
                if chunk.role == "agent":
                    print(chunk, end="", flush=True)
            print()

            print(f"Agent: {await result}\n")

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

    Now, run your script:

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

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

    **What just happened?**

    * We spawned an agent with a premise describing its role.
    * The `StreamLogger` lets us stream the agent's thinking as it runs.
    * We passed tools to `agent.call()` — the agent automatically decides when to use them.
    * The agent maintains conversation history, so it remembers context across messages.
  </Tab>

  <Tab title="TypeScript">
    ```typescript wrap main.ts theme={null}
    import { spawn } from '@symbolica/agentica';
    import * as readline from "readline";

    // Define your tools here!
    function myTool(arg: string): string {
      return `Result for: ${arg}`;
    }

    async function main() {
      await using agent = await spawn({ premise: "You are a helpful assistant." });

      const rl = readline.createInterface({
        input: process.stdin,
        output: process.stdout,
      });

      const question = (prompt: string): Promise<string> =>
        new Promise((resolve) => rl.question(prompt, resolve));

      console.log("Agent ready! Type 'quit' to exit.\n");

      while (true) {
        const userInput = await question("You: ");
        if (userInput.toLowerCase() === "quit") break;

        // Stream the agent's response
        const result = await agent.call<string>(
          userInput,
          { myTool },  // Pass your tools here
          {
            listener: (iid: string, chunk: any) => {
              if (chunk.role === "agent" && chunk.content) {
                process.stdout.write(chunk.content);
              }
            },
          }
        );
        console.log();

        console.log(`Agent: ${result}\n`);
      }

      rl.close();
    }

    main();
    ```

    Now, run your script:

    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm run main
      ```

      ```bash npm theme={null}
      npm run main
      ```

      ```bash bun theme={null}
      bun main.ts
      ```
    </CodeGroup>

    **What just happened?**

    * We spawned an agent with a premise describing its role.
    * The `listener` callback streams the agent's thinking as it runs.
    * We passed tools to `agent.call()` — the agent automatically decides when to use them.
    * The agent maintains conversation history, so it remembers context across messages.
  </Tab>
</Tabs>