Quickstart

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

Setup your project in chat-with-tools.

Write your first Agentica agent.

Installation

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

Get your API key from the login page.

Python+uv
Python+pip
TypeScript+Node
TypeScript+Bun

Prerequisites:

Python version 3.12.*
uv package manager
Your Agentica API key from the login page

Setup your virtual environment

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.

export AGENTICA_API_KEY="your-key-here"

Then, start editing your main.py file.

Prerequisites:

Python version 3.12.*
pip package manager
Your Agentica API key from the login page

Check your Python version.

python --version
# should be ~3.12.x

Setup your virtual environment

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.

export AGENTICA_API_KEY="your-key-here"

Then, start editing your main.py file.

Prerequisites:

Node.js version >=20.0.0
npm or pnpm package manager
Your Agentica API key from the login page

node --version
# should be >=20.0.0

Create your project

mkdir chat-with-tools
cd chat-with-tools
pnpm init
pnpm add -D typescript
pnpm exec tsc --init
# get your package from the login page
pnpm add @symbolica/agentica
pnpm exec agentica-setup
pnpm install

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

"scripts": {
  "build": "tspc main.ts", 
  "main": "pnpm run build && node main.js"
}

Set your API key

export AGENTICA_API_KEY="your-key-here"

Then, start editing your main.ts file.

Prerequisites:

Bun runtime
Your Agentica API key from the login page

Create your project

mkdir chat-with-tools
cd chat-with-tools
bun init
# get your package from the login page
bun add @symbolica/agentica
bunx agentica-setup

Durning setup, choose “Bun plugin” as the build tool.Set your API key

export AGENTICA_API_KEY="your-key-here"

Then, start editing your main.ts file.

Your First Agent

Python
TypeScript

main.py

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:

uv run main.py

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.

main.ts

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:

pnpm run main

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.

Getting Started

Core Concepts

Guides

Integrations

Installation

Your First Agent

Getting Started

Core Concepts

Guides

Integrations

​Installation

​Your First Agent

Installation

Your First Agent