State Management

AgentScript provides state management at two levels:

Agent State

Each time you run an agent with executeAgent, you get an AgentState object, that has properties such as:

• id: (string): The unique identifier for the current execution
• root: (StackFrame): The StackFrame object that contains the current execution state
• complete: (boolean): Indicates whether the agent has finished executing
• output (any, optional): Contains the result of the execution

You can use this state to inspect how the agent is executing, and to build interfaces to manage running agents.

Tool State

Tools can maintain internal state between calls. This state is specific to the individual tool call within a given execution of an agent.

When you define a tool with the defineTool, you can provide a state schema:

import { defineTool } from 'agentscript-ai/core';
import * as s from 'agentscript-ai/schema';
 
const myTool = defineTool({
  name: 'myTool',
  description: 'My custom tool that uses state',
  input: {
    someInput: s.string()
  },
  state: {
    count: s.number()
  },
  handler: ({input, state}) => {
    if(!state.count) {
      state.count = 0
    }
 
    console.log('Current count: ', state.count);
    state.count = state.count + 1;
  },
});

The tool's handler function receives its current state. If the state is not initialized, it will receive a default value based on the schema passed in. The modifications to the state object will persist between subsequent calls of this tool.