​
Agents

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

​
Creating an Agent

import { createAgent, createOpenAILLM } from "spinai";
import { getCustomerInfo, updateProfile } from "./actions";

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

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

​
Custom Response Formats

You can specify a response format to get structured data back from the agent:

interface CustomerInfo {
  name: string;
  plan: string;
  nextBilling: string;
}

const supportAgent = createAgent<CustomerInfo>({
  instructions: "You are a customer support agent",
  actions: [getCustomerInfo, getSubscriptionStatus],
  llm,
  responseFormat: {
    type: "json",
    schema: {
      type: "object",
      properties: {
        name: { type: "string" },
        plan: { type: "string" },
        nextBilling: { type: "string" },
      },
      required: ["name", "plan", "nextBilling"],
    },
  },
});

// Response will be typed as CustomerInfo
const { response } = await supportAgent({
  input: "What's my subscription status?",
  state: {},
});

console.log(response.plan); // "Pro Plan"
console.log(response.nextBilling); // "2024-04-01"

​
Using Agents

Agents are async functions that take input and return responses:

const { response, context } = await agent({
  input: "I need help with my order",
  state: {}, // Optional initial state
});

​
Agent Configuration

interface AgentConfig {
  instructions: string; // Guide agent behavior
  actions: Action[]; // Available actions
  llm: BaseLLM; // LLM for decisions
  training?: {
    // Optional training overrides
    systemInstructions?: string;
    completionInstructions?: string;
  };
}

​
LLM Support

SpinAI supports multiple LLMs out of the box.

See LLM Support for more details on configuring different models.

​
Best Practices

  1. Clear Instructions

    // Good
instructions: "You are a support agent that helps users with order issues";
// Bad
instructions: "Help users";

  2. Focused Action Sets Only provide actions relevant to the agent’s purpose:

    // Support agent
actions: [getCustomerInfo, getOrderStatus, createTicket];

  3. State Management Initialize state when needed:

    await agent({
  input: "Check my order",
  state: {
    customerId: "123",
    region: "US",
  },
});

​
Next Steps

Actions

Learn about creating actions

Task Loop

Understand how agents make decisions

Task LoopActions