AgentScript Guide

AgentScript is the safe JavaScript subset that runs inside codecall:execute. It gives LLMs the power to orchestrate multiple tools, filter data, and build workflows — while the security pipeline ensures every script is validated, transformed, and sandboxed before execution.

Core APIs

callTool(name, input, options?)

Call a registered tool and get the result.

// Basic call - throws on error by default
const users = await callTool('users:list', { limit: 100 });

// Safe pattern - returns result object instead of throwing
const result = await callTool('users:get', { id: 'maybe-invalid' }, {
  throwOnError: false
});

if (result.success) {
  return result.data;
} else {
  return { error: result.error.message };
}

Parameters:

Parameter	Type	Required	Description
`name`	`string`	Yes	Tool name (e.g., `'users:list'`)
`input`	`object`	Yes	Input arguments for the tool
`options`	`object`	No	Execution options

Options:

Option	Type	Default	Description
`throwOnError`	`boolean`	`true`	When `false`, returns `{ success, data, error }` instead of throwing

Return value (when throwOnError: false):

// Success
{ success: true, data: { /* tool result */ } }

// Failure
{ success: false, error: { message: string, code?: string } }

getTool(name)

Get metadata about a tool (name, description, schemas) without calling it.

const meta = getTool('users:list');
console.log(meta.description);    // "List users with optional filtering"
console.log(meta.inputSchema);    // { type: "object", properties: { ... } }

codecallContext

Read-only context object passed in the codecall:execute request. Use it to access tenant information, user IDs, or any custom data.

const tenantId = codecallContext.tenantId;
const userId = codecallContext.userId;

// Cannot modify - object is frozen
codecallContext.tenantId = 'other'; // ❌ Throws error

console (if enabled)

Standard console methods, captured in the response logs array.

console.log('Processing users...');
console.warn('Large dataset detected');
console.error('Validation failed');

Console is only available if vm.allowConsole: true in plugin config. Logs are returned in the logs array of the response.

__safe_parallel(fns, options?)

Execute multiple async operations in parallel with controlled concurrency.

const userIds = ['user-1', 'user-2', 'user-3', 'user-4', 'user-5'];

const users = await __safe_parallel(
  userIds.map(id => () => callTool('users:get', { id })),
  { maxConcurrency: 3 }
);

return users;  // Array of results in same order as input

Options:

Option	Type	Default	Max	Description
`maxConcurrency`	`number`	10	20	Max concurrent operations

Limits:

Limit	Value	Error
Max array size	100	`Cannot execute more than 100 operations in parallel`
Max concurrency	20	Silently clamped

Error behavior: If any operation fails, the entire __safe_parallel call fails with a combined error message.

try {
  const results = await __safe_parallel([
    () => callTool('users:get', { id: 'valid' }),
    () => callTool('users:get', { id: 'invalid' }),  // Throws
    () => callTool('users:get', { id: 'also-valid' }),
  ]);
} catch (error) {
  // "1 of 3 parallel operations failed:
  //   [1]: User not found"
}

What You Can Write

AgentScript supports a safe subset of JavaScript:

// ✅ Tool calls
const users = await callTool('users:list', { limit: 100 });

// ✅ Variables (const, let)
const filtered = users.filter(u => u.active);
let count = 0;

// ✅ Arrow functions
const names = users.map(u => u.name);
const total = users.reduce((sum, u) => sum + u.score, 0);

// ✅ Bounded loops
for (let i = 0; i < users.length; i++) { count++; }
for (const user of users) { console.log(user.name); }

// ✅ Template literals
const greeting = `Hello, ${user.name}!`;

// ✅ Destructuring
const { name, email } = user;
const [first, ...rest] = users;

// ✅ Try/catch
try {
  const data = await callTool('api:fetch', { url: '/data' });
} catch (e) {
  return { error: e.message };
}

// ✅ Safe built-ins
const max = Math.max(1, 2, 3);
const parsed = JSON.parse('{"a":1}');
const keys = Object.keys(obj);
const now = new Date();

// ✅ Context access (read-only)
const tenant = codecallContext.tenantId;

// ✅ Return values
return { count, names, total };

What Is Blocked

eval / Function / AsyncFunction

Dynamic code execution is blocked to prevent injection attacks.

eval('malicious code');              // ❌ Blocked
new Function('return process')();    // ❌ Blocked

require / import

Module loading is blocked to prevent sandbox escape.

require('fs');                        // ❌ Blocked
import('child_process');              // ❌ Blocked

Global access

No access to Node.js globals or the host environment.

process.env.SECRET;                   // ❌ Blocked
global.something;                     // ❌ Blocked
globalThis.escape;                    // ❌ Blocked
this.constructor;                     // ❌ Blocked

while / do-while / for-in

Unbounded loops are blocked to prevent infinite execution.

while (true) {}                       // ❌ Blocked
do {} while (condition);              // ❌ Blocked
for (key in obj) {}                   // ❌ Blocked (prototype walking)

Use for-of or for with bounds instead.

Prototype access

Prototype manipulation is blocked to prevent pollution attacks.

obj.__proto__ = {};                   // ❌ Blocked
obj.constructor.prototype.x = 1;     // ❌ Blocked
Object.prototype.polluted = true;    // ❌ Blocked

Reserved prefixes

Identifiers starting with __ag_ or __safe_ are reserved for the runtime.

const __ag_hack = 'foo';             // ❌ Blocked
let __safe_bypass = 123;             // ❌ Blocked

Timers

Async escape via timers is blocked.

setTimeout(fn, 100);                  // ❌ Blocked
setInterval(fn, 100);                 // ❌ Blocked
setImmediate(fn);                     // ❌ Blocked

Regular expressions (strict mode)

In AgentScript’s strict mode, regex literals are blocked to prevent ReDoS.

/pattern/.test(str);                  // ❌ Blocked in strict mode

Error Handling Patterns

Basic: throwOnError

// Default: throws on error
const users = await callTool('users:list', { limit: 100 });

// Safe: returns result object
const result = await callTool('users:get', { id: 'maybe-invalid' }, {
  throwOnError: false
});

if (result.success) {
  return { user: result.data };
} else {
  return { error: result.error.message, fallback: 'default-user' };
}

Retry Pattern

const retryTool = async (toolName, args, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const result = await callTool(toolName, args, { throwOnError: false });

    if (result.success) {
      return result.data;
    }

    // Don't retry non-transient errors
    if (result.error.code === 'NOT_FOUND' || result.error.code === 'VALIDATION_ERROR') {
      throw new Error(result.error.message);
    }

    if (attempt === maxRetries) {
      throw new Error(`Failed after ${maxRetries} attempts: ${result.error.message}`);
    }

    console.warn(`Attempt ${attempt} failed, retrying...`);
  }
};

const data = await retryTool('api:fetch', { url: '/data' });

Fallback Pattern

// Try primary, fall back to secondary
const result = await callTool('cache:get', { key: 'users' }, { throwOnError: false });

const users = result.success
  ? result.data
  : await callTool('db:query', { table: 'users' });

return users;

Partial Success Pattern

const ids = ['id-1', 'id-2', 'id-3', 'id-4'];
const results = { success: [], failed: [] };

for (const id of ids) {
  const result = await callTool('users:get', { id }, { throwOnError: false });

  if (result.success) {
    results.success.push(result.data);
  } else {
    results.failed.push({ id, error: result.error.message });
  }
}

return {
  users: results.success,
  errors: results.failed,
  successRate: results.success.length / ids.length,
};

Parallel Execution

Use __safe_parallel for concurrent operations:

Batch Fetching

const ids = await callTool('users:listIds', { limit: 50 });
const users = await __safe_parallel(
  ids.map(id => () => callTool('users:get', { id }))
);
return users;

Parallel Aggregation

const [orders, users, metrics] = await __safe_parallel([
  () => callTool('orders:list', { status: 'pending' }),
  () => callTool('users:list', { role: 'admin' }),
  () => callTool('analytics:getMetrics', {}),
]);

return {
  pendingOrders: orders.length,
  adminCount: users.length,
  metrics,
};

Best Practices

Keep scripts focused. Each script should do one logical operation. Break complex workflows into separate codecall:execute calls rather than writing mega-scripts.

Paginate large datasets. Don’t fetch everything at once. Use limit and offset parameters, and filter server-side.

Use throwOnError: false for optional operations. When a failure in one tool call shouldn’t abort the entire script, use the safe pattern.

Return only what you need. Filter and transform data inside the script so the LLM receives a minimal, focused result instead of raw tool output.

Next Steps

API Reference

Complete meta-tool schemas, error codes, and debugging guide

Examples & Recipes

Real-world patterns built with AgentScript

Security Model

How AgentScript is validated, transformed, and sandboxed

Configuration

VM presets, iteration limits, and console settings

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Core APIs

callTool(name, input, options?)

getTool(name)

codecallContext

console (if enabled)

__safe_parallel(fns, options?)

What You Can Write

What Is Blocked

Error Handling Patterns

Basic: throwOnError

Retry Pattern

Fallback Pattern

Partial Success Pattern

Parallel Execution

Batch Fetching

Parallel Aggregation

Best Practices

Next Steps

API Reference

Examples & Recipes

Security Model

Configuration

​Core APIs

​callTool(name, input, options?)

​getTool(name)

​codecallContext

​console (if enabled)

​__safe_parallel(fns, options?)

​What You Can Write

​What Is Blocked

​Error Handling Patterns

​Basic: throwOnError

​Retry Pattern

​Fallback Pattern

​Partial Success Pattern

​Parallel Execution

​Batch Fetching

​Parallel Aggregation

​Best Practices

​Next Steps

API Reference

Examples & Recipes

Security Model

Configuration

Core APIs

callTool(name, input, options?)

getTool(name)

codecallContext

console (if enabled)

__safe_parallel(fns, options?)

What You Can Write

What Is Blocked

Error Handling Patterns

Basic: throwOnError

Retry Pattern

Fallback Pattern

Partial Success Pattern

Parallel Execution

Batch Fetching

Parallel Aggregation

Best Practices

Next Steps