SpinAI Framework

SpinAI provides two distinct ways to handle data within an agent's lifecycle: Parameters and State. Choosing the right one depends on whether the data is dynamic/LLM-driven or static/persistent.

Parameters

Parameters are values passed into actions by the LLM during the task loop.

• Nature: Dynamic and per-action.
• Source: Determined by the LLM based on the action's parameters schema.
• Use Case: Best for inputs the LLM needs to decide on (e.g., a specific number to add, a search query, or a quantity).
• Lifecycle: Derived from previous action results and current state.

State

State is a persistent object used for data that lives across the entire interaction.

• Nature: Persistent and static.
• Access: Accessed via context.state inside actions, and via the state object returned after the agent finishes.
• Modification: Can only be modified by your Actions.
• Use Case: Best for values that shouldn't be guessed by an LLM, such as userId, userEmail, or session-specific configuration.

The Task Loop is the core decision-making engine of a SpinAI agent. It orchestrates the workflow by managing planning, action execution, and response generation.

The Workflow Lifecycle

1. Planning and Reasoning: The agent analyzes user input, current state, and previous results to decide which actions to run. It provides explicit reasoning and returns a list of action IDs with their required parameters.
2. Parallel Action Execution: If actions are required, the loop executes them in parallel. Each action receives the full context and specific parameters. Results are captured and added to the conversation history.
3. Response Generation: Once no further actions are needed, the agent generates a final response using the accumulated context and state. This response can be plain text or structured data, depending on your responseFormat configuration.

Key Features

• State Management: Maintains state throughout the entire interaction.
• Parallelism: Maximizes efficiency by running non-dependent actions simultaneously.
• Observability: Provides comprehensive logging, including reasoning steps, token usage, cost, and duration.
• Error Recovery: Gracefully handles action execution errors by feeding error information back to the agent for potential recovery.

graph TD
    A[Agent Called] --> B[Initialize Context & State]
    B --> C[Generate Planning Decision]
    C --> D{Actions Needed?}
    D -->|Yes| E[Execute Actions in Parallel]
    E --> F[Capture Results]
    F --> C
    D -->|No| G[Generate Final Response]
    G --> H[Return Response with State]

When designing actions, choose between using parameters or context.state based on how the data should be handled:

Key Distinction: Returning a value from run() makes it available to the LLM to use as a parameter for other actions, but that value only lives in the message history. Setting context.state makes the value available to the system/runtime regardless of the message history.

Actions are the functions or tools that an agent can call to perform tasks.

Key characteristics of Actions:

• Inputs/Outputs: They have clearly defined inputs (via parameters) and outputs.
• State Access: They can maintain and access state through a provided context.
• Dependencies: Actions can depend on other actions.
• Execution Order: Actions are executed in Directed Acyclic Graph (DAG) order.

To define an action, use the createAction function. You must provide a unique id, a description for the LLM to understand when to use it, a JSON Schema for parameters, and an asynchronous run function to execute the logic.

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;
  },
});