​
Overview

A simple calculator agent that demonstrates core SpinAI concepts. The agent:

  • Processes mathematical expressions in natural language
  • Dynamically chooses between addition and subtraction operations
  • Returns numerical results

​
Structure

src/
├── actions/
│   ├── sum.ts     # Addition operation
│   └── minus.ts   # Subtraction operation
└── index.ts       # Main agent setup

​
Quick Start

  1. Create a new project:
npx create-spinai

  1. Select the default template

  2. Set up your environment:

# .env
OPENAI_API_KEY=your-key-here

​
How It Works

  1. Agent Setup: Uses OpenAI (swappable with any supported LLM) for decision making
  2. Available Actions:
    • sum: Adds two numbers
    • minus: Subtracts two numbers
  3. Input Processing: Converts natural language (e.g. “What is 5 plus 3 - 1?”) into mathematical operations
  4. State Management: Tracks calculation progress through multiple operations

​
Example Usage

import { createAgent } from "spinai";
import { openai } from "@ai-sdk/openai";
import { sum } from "./actions/sum";
import { minus } from "./actions/minus";

const calculatorAgent = createAgent({
  instructions: `You are a calculator agent that helps users perform mathematical calculations.`,
  actions: [sum, minus],
  model: openai("gpt-4o"),
});

async function main() {
  const { response } = await calculatorAgent({
    input: "What is 5 plus 3 - 1?",
  });

  console.log(response);
}

main().catch(console.error);

​
Next Steps

Here are some easy things you can add to get your hands dirty and learn how Spin works

  • Add a multiply action
  • Add a division action
  • Try to use the state returned by the agent call to keep a running sum that you can continue performing mathematical operations on, like a real calculator
  • Add any agentId (i.e “calculator-agent”) and your SpinAPI key to the createAgent parameters and track your model on our dashboard.

This example serves as a basic introduction to Spin’s framework.