AgentScript SDK

Unlike traditional Re-act agents that perform iterative tool calls via LLM loops, AgentScript prompts an LLM to generate a plan expressed as a subset of JavaScript (AgentScript).

The Workflow:

1. Define Runtime: Set up tools and optionally input/output variables.
2. Define Task: Provide a prompt for the agent to execute.
3. Code Generation: The LLM generates AgentScript code representing the execution plan.
4. AST Parsing: The generated code is parsed into an Abstract Syntax Tree (AST).
5. Safe Execution: The AST is executed in a dedicated, safe interpreter (not directly in Node.js). This allows for features like execution pausing, serialization for state persistence, and human-in-the-loop interactivity.

To use the AgentScript SDK in your project, install the agentscript-ai package using npm.

npm install agentscript-ai

An Agent represents an active or completed execution of an AgentScript. It is composed of a unique id, a createdAt timestamp, an AgentRuntime (containing the code and its hash), and an AgentDefinition which specifies the tools, inputs, and outputs available to the agent.

An agent's lifecycle is tracked via its AgentState. The state is a union of two possible conditions:

1. Running: The status is any StackFrameStatus except 'done'. In this state, the output property is undefined because the execution has not finished.
2. Complete: The status is exactly 'done'. In this state, the output property is populated with an AgentOutput of type TOutput.

Agents can also maintain a chain of AgentState[], representing a sequence of previous agent executions.

Tools can interact with events. A ToolEvent represents an interaction with the tool.

ToolEvent structure:

• timestamp: Date of the event.
• payload: The data associated with the event.
• processed: A boolean indicating if the event has been handled.

ToolEventSerialized structure (for persistence/wire format):

• timestamp: number (Unix timestamp).
• payload: number (Index of the payload in the heap).
• processed: boolean.

The Heap format is a recursive serialization structure used to represent complex JavaScript values as a flat array of HeapValue entries. This format allows for the serialization of non-primitive types (like Arrays, Objects, Sets, and Dates) by using tagged arrays where the first element is a type identifier (e.g., 'a' for Array, 'o' for Object) followed by the serialized data. This structure is designed to handle recursive references and complex data types in a way that can be reconstructed.

// Example representation of the Heap structure:
// A Heap is an array of HeapValue
type Heap = HeapValue[];

The RuntimeModule type defines how tools are organized and made available to an agent. It is a recursive structure that allows for namespaced tools:

type RuntimeModule = {
    [name: string]: ToolDefinition | RuntimeModule;
};

This means you can provide a flat list of tools or a nested hierarchy where tools are grouped under specific namespaces.

An AgentDefinition is the core configuration object used to describe an agent's capabilities and interface. It uses the following types:

• TTools (AgentTools): A RuntimeModule which is a recursive object where keys are tool names and values are either a ToolDefinition or another nested RuntimeModule.
• TInput (AgentInputBase): A Record<string, s.Schema> defining the keys and types of the input object.
• TOutput (AgentOutputBase): A single s.Schema defining the shape of the agent's return value.

Defining these explicitly allows for type inference of the agent's inputs and outputs during development.

The LinearClient is a service provided by the @agentscript-ai/linear package that wraps a GraphQLClient for interacting with the Linear API. To initialize the service, you must provide a LINEAR_API_KEY via the LINEAR_API_KEY environment variable. The service automatically configures the Authorization header for requests to https://api.linear.app/graphql using this key.

// Ensure the environment variable is set in your environment
// export LINEAR_API_KEY=your_api_key_here

import { LinearClient } from '@agentscript-ai/linear';

// The service is managed via @nzyme/ioc and uses the LINEAR_API_KEY
// to instantiate a GraphQLClient configured for Linear's endpoint.

You can configure ESLint for your project by importing and spreading predefined configuration presets from the @agentscript-ai/eslint package. This allows you to quickly apply standard rules for common JavaScript/TypeScript patterns, JSDoc documentation, and package.json validation.

Available presets:

• common(): Base configuration for general project rules.
• typescript(): Specific rules and configurations for TypeScript files.
• jsdoc(): Rules for enforcing and validating JSDoc comments.
• packageJson(): Rules for validating package.json structure and content.

import { common, jsdoc, packageJson, typescript } from '@agentscript-ai/eslint';

export default [
    ...common(),
    ...typescript(),
    ...jsdoc(),
    ...packageJson(),
];

To set up ESLint for an AgentScript project, import the configuration presets from @agentscript-ai/eslint. The recommended setup involves spreading several specialized configuration functions into the exported array to cover common rules, TypeScript support, JSDoc documentation requirements, and package.json validation.

Available presets:

• common(): Base configuration rules.
• typescript(): Rules and parser settings for TypeScript files.
• jsdoc(): Rules for enforcing JSDoc documentation standards.
• packageJson(): Rules for validating package.json files.

import { common, jsdoc, packageJson, typescript } from '@agentscript-ai/eslint';

export default [
    ...common(),
    ...typescript(),
    ...jsdoc(),
    ...packageJson(),
];

AgentScript provides a set of pre-configured ESLint presets via the @agentscript-ai/eslint package to ensure consistent code quality across projects. You can compose your eslint.config.js by importing and spreading these functional presets into your configuration array.

Available presets:

• common(): Base configuration for general project rules.
• typescript(): Configuration optimized for TypeScript projects.
• jsdoc(): Rules and plugins for enforcing JSDoc documentation standards.
• packageJson(): Rules for validating package.json files.

import { common, jsdoc, packageJson, typescript } from '@agentscript-ai/eslint';

export default [
    ...common(),
    ...typescript(),
    ...jsdoc(),
    ...packageJson(),
];

To set up ESLint for an AgentScript project, use the @agentscript-ai/eslint package. The recommended configuration is an array of preset configurations that cover common rules, TypeScript support, JSDoc documentation requirements, and package.json validation.

Import the following presets from @agentscript-ai/eslint and spread them into your eslint.config.js export array:

• common(): Base rules used across the project.
• typescript(): Rules and parser settings for TypeScript files.
• jsdoc(): Rules for enforcing JSDoc documentation standards.
• packageJson(): Rules for validating package.json files.

import { common, jsdoc, packageJson, typescript } from '@agentscript-ai/eslint';

export default [
    ...common(),
    ...typescript(),
    ...jsdoc(),
    ...packageJson(),
];