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:
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 };
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"
}
{
"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"
}
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 |
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. 
