Agents

Agents are the core building blocks of SpinAI. They combine LLMs with actions to solve tasks.

Quick Start

import { createAgent, createOpenAILLM } from "spinai";
import { searchProducts, createOrder } from "./actions";

// Initialize your LLM
const llm = createOpenAILLM({
  apiKey: process.env.OPENAI_API_KEY,
});

// Create an agent
const agent = createAgent({
  instructions: "You are a helpful shopping assistant",
  actions: [searchProducts, createOrder],
  llm,
});

// Use the agent
const { response } = await agent({
  input: "Find me a red t-shirt under $30",
});

Configuration Options

Agent Creation Parameters

ParameterTypeRequiredDescription
instructionsstringYesInstructions that guide the agent’s behavior
actionsAction[]YesArray of actions the agent can perform
llmBaseLLMYesLanguage model for decision making
spinApiKeystringNoAPI key for SpinAI dashboard integration
agentIdstringNoUnique identifier for the agent in SpinAI dashboard
debug"none" | "default" | "verbose" | "all"NoDebug logging level
responseFormatJSONSchemaNoSchema for structured responses, defaults to string

Agent Execution Parameters

ParameterTypeRequiredDescription
inputstringYesUser input or task description
stateRecord<string any>NoInitial state for the execution
externalCustomerIdstringNoCustomer identifier for tracking

Return Values

ParameterTypeDescription
responseT | stringAgent’s response (typed if responseFormat provided)
totalCostCentsnumberTotal cost of LLM calls in cents
totalDurationMsnumberTotal execution time in milliseconds
sessionIdstringUnique identifier for the conversation
interactionIdstringUnique identifier for this specific interaction
stateRecord<string, any>Final state after execution

Use Cases

1. Basic Agent

Simple agent that responds to queries:

const agent = createAgent({
  instructions: "You are a helpful assistant",
  actions: [searchKnowledge, respondToUser],
  llm,
});

const { response } = await agent({
  input: "How do I reset my password?",
});

2. Structured Responses

Agent that returns typed data:

interface OrderStatus {
  orderId: string;
  status: "pending" | "shipped" | "delivered";
  estimatedDelivery?: string;
}

const orderAgent = createAgent<OrderStatus>({
  instructions: "Track order status",
  actions: [getOrderDetails],
  llm,
  responseFormat: {
    type: "object",
    properties: {
      orderId: { type: "string" },
      status: { type: "string", enum: ["pending", "shipped", "delivered"] },
      estimatedDelivery: { type: "string" },
    },
    required: ["orderId", "status"],
  },
});

3. Dashboard Integration

Agent with monitoring enabled:

const agent = createAgent({
  instructions: "Handle customer support",
  actions: [getCustomer, createTicket],
  llm,
  spinApiKey: process.env.SPINAI_API_KEY,
  agentId: "support-agent",
  debug: "verbose",
});

const { response, totalCostCents } = await agent({
  input: "I need help with my order",
  externalCustomerId: "customer_123",
});

4. Session Management with Reruns

Maintaining context across interactions:

// Initial interaction
const { response, sessionId, state } = await agent({
  input: "Create a ticket for my broken laptop",
  state: { customerId: "123" },
});

// Follow-up using .rerun()
const { response: updatedResponse } = await agent.rerun({
  sessionId: sessionId,
  input: "Add that it's a MacBook Pro",
  state: state,
});

Debug Logging

Different debug levels provide varying amounts of information:

LevelInformation Shown
noneNo logging
defaultBasic flow and metrics
verboseAdds reasoning and parameters
allAdds full prompts and details

Example output (default level):

🤖 Planning next actions (took 234ms, cost 0.5¢)
⚡ Executing getCustomerInfo (took 123ms)
   Parameters: {"customerId": "123"}
📊 Task complete (took 892ms, cost 1.2¢)

Best Practices

  1. Clear Instructions

    instructions: "You are a support agent that helps users with order issues";
    
  2. Focused Action Sets

    actions: [getCustomerInfo, getOrderStatus, createTicket];
    
  3. State Management

    state: {
      customerId: "123",
      region: "US",
    }
    

Next Steps