Introduction

​

What is SpinAI?

SpinAI is a lightweight TypeScript framework for building AI agents that can:

• Execute actions in a specific order
• Maintain state between actions
• Make decisions using any LLM
• Handle complex dependencies
• Maintain observability of the agent’s state, actions, and decision making throughout the agent’s lifecycle.

​

Key Concepts

​

Agents

An agent is a self-contained, stateful entity that:

• Receives user input
• Decides which actions to take / which tools to call
• Maintains state between actions
• Provides text or custom JSON responses back to the user
• Can use any LLM supported by Vercel’s AI SDK for decision making

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

​

Actions

Actions are functions / tools that your agent can call.

• Have clear inputs and outputs
• Maintain and access state through context
• Can depend on other actions
• Are executed in DAG (directed acyclic graph) order

export const sum = createAction({
  id: "sum",
  description: "Adds two numbers together.",
  parameters: {
    type: "object",
    properties: {
      a: { type: "number", description: "First number to add" },
      b: { type: "number", description: "Second number to add" },
    },
    required: ["a", "b"],
  },
  async run({ parameters }): Promise<number> {
    const { a, b } = parameters || {};
    return a + b;
  },
});

​

Why SpinAI?

• 🎯 Focused: Built specifically for action-oriented AI agents
• 🔄 Flexible: Works with any LLM supported by Vercel’s AI SDK
• 📦 Simple: Minimal boilerplate, maximum productivity
• 🛠️ Type-safe: Built with TypeScript for robust development
• 🪶 Light: Zero dependencies beyond your chosen LLM

​

Next Steps