Agent Code Execution: Run JavaScript in a Secure Sandbox

Language models are excellent at reasoning, summarizing, and making decisions — but they’re unreliable for precise math, complex JSON manipulation, or structured HTTP calls to external APIs. Code Execution closes that gap. When you enable it on an agent, the agent can write JavaScript or TypeScript to solve a problem and run it in a secure sandbox, then use the real output to continue its work. If you’ve ever seen an LLM confidently produce a wrong calculation, this is the fix.

What Code Execution Enables

Code Execution is the right tool when determinism, precision, or structured API handling matters:

Calling third-party APIs with structured request and response handling — authentication headers, error checking, retry logic
Transforming and validating JSON payloads — reshaping, filtering, and normalizing complex data structures
Running deterministic calculations — scoring models, weighted rankings, currency conversions, statistical computations
Building lightweight data pipelines — fetch, transform, filter, and return in a single execution

Code Execution is not designed for long-running batch jobs, heavy background processing, or operations with large side effects that haven’t been explicitly requested by the user.

How It Works

When Code Execution is enabled on an agent, the agent decides on its own whether writing code is the right approach for a given task. Here’s the full flow:

The agent receives a task and determines that code is the most reliable path
The agent writes JavaScript or TypeScript to accomplish it
The sandboxed runtime executes the code under strict resource limits
The sandbox returns stdout, the return value, and any errors — the same feedback a developer would get in a terminal
The agent uses that output to respond to the user, pass results to another tool, or take the next step

The agent sees real output from real execution. There’s no hallucination risk on the computed values.

Enable Code Execution on an Agent

Open your agent

Navigate to your agent in Scout Studio.

Go to the Tools tab

Click the Tools tab in the agent editor.

Enable Code Execution

Toggle on Code Execution from the native tools list.

Save and test

Save your agent and send a prompt that requires a calculation, data transform, or API call. Review the Logs tab to see the code the agent generated and the output it received.

A Real Example

Say your agent receives this prompt: “Fetch the top five accounts from our CRM API and score them by revenue.” The agent generates and executes something like this:

JavaScript

const response = await fetch("https://api.example.com/accounts", {
  headers: { Authorization: `Bearer ${env.CRM_API_KEY}` }
});

if (!response.ok) {
  throw new Error(`CRM API error: ${response.status} ${response.statusText}`);
}

const accounts = await response.json();

const scored = accounts
  .map(a => ({
    name: a.name,
    score: (a.annual_revenue * 0.6) + (a.employee_count * 0.4),
    revenue: a.annual_revenue,
    employees: a.employee_count
  }))
  .sort((a, b) => b.score - a.score)
  .slice(0, 5);

return { ok: true, top_accounts: scored };

The agent gets the structured result back and can summarize it, pass it to another tool, or return it directly to the user. The scoring logic runs exactly as written — no approximation, no hallucination.

Prompt Examples

These prompts naturally lead an agent to use Code Execution:

"Call this REST API endpoint, normalize the response, and return a table of active accounts."

"Compute weighted lead scores from this JSON payload and return the top 10 with reasons."

"Write JavaScript to parse these webhook events and group failures by error code."

"Fetch pricing data from this API, convert all currencies to USD, and summarize deltas by plan."

"Validate this JSON schema against our expected format and return a list of violations."

Instruction Snippet

Add this block to your agent’s instructions to guide when and how it uses Code Execution:

When a task requires deterministic compute, structured API integration,
or complex data transforms:

1. Prefer Code Execution over in-context reasoning for calculations,
   parsing, and strict data transforms.
2. Keep generated code minimal and focused on the specific task.
3. Validate required input fields before executing.
4. Return structured outputs with clear, consistent field names.
5. Handle API errors explicitly — check response status codes and
   throw descriptive errors on failure.
6. Explain failures in the final response with enough detail that
   the user can take corrective action.

Consistent Output Shapes

Give your agent a standard structure for both success and failure responses. Consistent shapes make downstream tool chaining predictable and make it easier for both the agent and humans to understand what happened. Success:

{
  "ok": true,
  "data": { "top_accounts": [] },
  "summary": "Fetched and scored 5 accounts from CRM API"
}

Failure:

{
  "ok": false,
  "error_code": "UPSTREAM_TIMEOUT",
  "message": "CRM API timed out after 10 seconds",
  "next_action": "Retry with a smaller batch size or contact CRM support"
}

Using ok: true/false as a top-level field lets the agent branch on results without parsing error strings — and makes log review much faster.

Security Model

Code Execution runs in a sandboxed runtime with strict resource limits. Your agent’s code cannot:

Access the filesystem outside the sandbox
Make outbound network calls to arbitrary destinations (unless explicitly allowed by your configuration)
Spawn persistent processes or background workers
Access other agents’ data or Scout’s internal systems

The sandbox is isolated per execution. Each run starts clean with no shared state from previous runs. Environment variables like API keys are injected by Scout — they are not exposed in plain text in the generated code or logs.

Before enabling Code Execution on a public-facing Copilot deployment, review your agent’s instructions carefully. Ensure the agent is instructed to confirm before taking high-impact actions and to avoid executing code that wasn’t explicitly requested by the user.

Code Execution vs. Workflow JavaScript Block

Scout offers two places to run JavaScript. Here’s when to use each:

	Agent Code Execution	Workflow JavaScript Block
When to use	The agent decides at runtime what code to write based on the task	The logic is predefined and should always run the same way
Who writes the code	The agent generates it dynamically	You write it once in the workflow builder
Best for	Dynamic API calls, variable transformations, context-dependent logic	Fixed pipelines, repeatable computations, versioned business logic
Versioning	Not versioned — generated fresh each run	Versioned with the workflow

Use Agent Code Execution when the agent needs to adapt its approach based on what it discovers. Use the Workflow JavaScript Block when the same logic runs identically every time and you want it reviewed, versioned, and locked.

Best Practices

Validate inputs before running. Instruct the agent to check that required fields exist and have expected types before executing code that depends on them. Keep outputs small and structured. Return only what’s needed for the next step — not the entire raw API response. This keeps context clean and downstream processing fast. Handle errors explicitly. Check HTTP status codes, catch exceptions, and return structured error objects rather than letting the code throw unhandled errors. Avoid side effects unless requested. Don’t write code that modifies external systems (CRM records, databases, emails) unless the user explicitly asked for that action. Log key decisions. Include a summary field in your return value explaining what the code did. This makes log review significantly faster when debugging.

Get Started

Agents

Workflows

Data & Storage

Integrations

Platform

Agent Code Execution: Run JavaScript in a Secure Sandbox

What Code Execution Enables

How It Works

Enable Code Execution on an Agent

A Real Example

Prompt Examples

Instruction Snippet

Consistent Output Shapes

Security Model

Code Execution vs. Workflow JavaScript Block

Best Practices

​What Code Execution Enables

​How It Works

​Enable Code Execution on an Agent

​A Real Example

​Prompt Examples

​Instruction Snippet

​Consistent Output Shapes

​Security Model

​Code Execution vs. Workflow JavaScript Block

​Best Practices

What Code Execution Enables

How It Works

Enable Code Execution on an Agent

A Real Example

Prompt Examples

Instruction Snippet

Consistent Output Shapes

Security Model

Code Execution vs. Workflow JavaScript Block

Best Practices