Quickstart

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

Setup your project in chat-with-tools.

Build an agent with the Agentica SDK.

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 Platform 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 Platform 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 Platform 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
pnpm add @symbolica/agentica
pnpm exec agentica-setup
pnpm install

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

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

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

"scripts": {
  "build": "tspc src/index.ts", 
  "main": "npm run build && node src/index.js"
}

Set your API key

export AGENTICA_API_KEY="your-key-here"

Then, start editing your src/index.ts file.

Prerequisites:

Bun runtime
Your Agentica Platform API key from the login page

Create your project

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

export AGENTICA_API_KEY="your-key-here"

Then, start editing your src/index.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

python 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

npm run main

bun main.ts

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

​Installation

​Your First Agent

Installation

Your First Agent