Skip to Content
🎉 Scout Docs 2.0 is here!
AgentsCode Execution

Code Execution

Sometimes an agent’s built-in reasoning isn’t enough. When you need precise math, complex JSON transforms, or a real HTTP call to a third-party API, Code Execution gives the agent a place to write and run JavaScript or TypeScript in a secure sandbox and get back real output.

If you’ve ever seen an LLM confidently hallucinate a calculation result, this is the fix.

What It Is Good For

  • Calling third-party APIs with structured request/response handling
  • Transforming and validating complex JSON payloads
  • Running deterministic calculations and scoring logic
  • Building lightweight data pipelines inside a single request

What It Is Not For

  • Long-running batch jobs
  • Unbounded crawling or heavy background processing
  • High-risk side effects without explicit user confirmation

How It Works

  1. The agent decides code is the right path for the task
  2. The agent writes JS or TS to solve it
  3. The sandbox executes the code with strict resource limits
  4. The sandbox returns the output to the agent
  5. The agent uses that output to respond or take the next step

The agent sees stdout, the return value, and any errors — the same feedback a developer would get in a terminal.

A Real Example

Say your agent gets this prompt: “Fetch the top 5 accounts from our CRM API and score them by revenue.”

The agent might generate and run something like this:

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}`);
}
 
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
  }))
  .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.

Enable It on an Agent

  1. Open your agent
  2. Go to the Tools tab
  3. Enable Code Execution
  4. Save and run a test prompt

Instruction Snippet

Add this to your agent instructions:

When a task requires deterministic compute or structured API integration:
 
1. Prefer Code Execution for calculations, parsing and strict data transforms.
2. Keep code minimal and focused on the current task.
3. Validate inputs before execution.
4. Return structured outputs with clear field names.
5. Explain failures with actionable error messages.

Prompt Examples

  • “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 top 10 with reasons.”
  • “Write JS to parse these webhook events and group failures by error code.”
  • “Fetch pricing data from this API, convert currencies to USD and summarize deltas by plan.”

Safety and Reliability Guidelines

  • Validate required fields before code execution
  • Keep outputs structured and small
  • Handle retries and API failures explicitly
  • Avoid destructive actions unless the user asked for them
  • Log key decisions in the agent response for traceability

Consistent Output Shapes

Give your agent a standard shape for both success and failure. This makes downstream tool chaining and human review predictable.

Success:

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

Failure:

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

Using ok: true/false as a top-level field lets your agent branch on results without parsing error strings.

Code Execution vs Workflow JavaScript Block

Use Agent Code Execution when the agent needs to decide logic dynamically at runtime — the agent picks what to write based on the task.

Use the Workflow JavaScript block when the logic should be predefined, repeatable and versioned in a workflow — you write the code once and it always runs the same way.

Next Steps

Built with ❤️ by Scout OS

Last updated on
ObservabilityAsync Interactions