Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Start with one focused agent, one turn, and one or two narrowly scoped tools. In JavaScript, an agent is a model-driven loop that follows instructions, decides whether to call an application function, observes the result, and returns an answer or next action. Add persistence, delegation, streaming, or sandboxing only when the product requirement demands it.
This guide uses the current OpenAI JavaScript Agents SDK shape as a concrete starting point, then explains how to choose an SDK, design tools safely, manage state, compose specialists, and operate longer-running workflows. Package and runtime support changes, so verify the current documentation before shipping.
What an AI agent is—and when JavaScript is enough
A conventional model call maps input to output. An agent adds a controlled loop around that call: the model receives instructions and context, selects from permitted tools, receives tool results, and continues until it can produce the requested result. Your application still owns the important boundaries: deployment, tool implementations, data access, persistence, approvals, and error handling.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Use an agent when the model must choose actions
- Use a normal function when the steps, inputs, and outputs are deterministic.
- Use a single model call when you need generation or classification but no tool selection.
- Use an agent when the model must choose among bounded capabilities, recover from intermediate results, or ask for missing information.
- Use multiple agents only when distinct scopes, instructions, or authorities make one agent difficult to control.
Define the job before choosing a framework
Write down the user outcome, permitted data sources, permitted side effects, approval points, and a testable definition of success. A vague goal such as “manage my business” produces an unbounded tool surface. A goal such as “check an order and draft a refund request, but never submit it without approval” is implementable and auditable.
#1 Best Overall
Build the smallest JavaScript agent
The OpenAI quickstart installs the Agents SDK and Zod, creates an Agent, and invokes run. Install in a server-side Node project:
npm install @openai/agents zodA minimal implementation is:
import { Agent, run } from "@openai/agents";
const agent = new Agent({
name: "Support helper",
instructions: "Answer using the supplied account tools; ask when required facts are missing.",
});
const result = await run(agent, "Explain the status of my order.");
console.log(result.finalOutput);Keep your provider credential on the server. Do not place a long-lived API key in browser JavaScript. For browser realtime clients, the Agents SDK repository describes a server-created, short-lived ephemeral client token instead of exposing the server key.
Inspect the result during development
The run result includes the final output and run history. Log structured events in development, but redact account data, tokens, cookies, and tool arguments that contain personal information. In production, retain enough correlation data to reconstruct failures without storing more user content than your policy allows.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteAdd tools with narrow permissions
A tool is an application capability the model may request. The model does not implement the capability: your function does. Give each tool a precise name, a description that explains when to use it, a validated schema, and a narrowly scoped implementation.
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";
const lookupOrder = tool({
name: "lookup_order",
description: "Return the current status for one order owned by the signed-in user.",
parameters: z.object({
orderId: z.string().regex(/^ORD-[0-9]+$/),
}),
execute: async ({ orderId }) => {
// Enforce authorization again inside the application boundary.
const order = await ordersForCurrentUser().get(orderId);
if (!order) return { found: false };
return { found: true, status: order.status, updatedAt: order.updatedAt };
},
});
const agent = new Agent({
name: "Order assistant",
instructions: "Use lookup_order for status questions. Never invent an order status.",
tools: [lookupOrder],
});
const result = await run(agent, "Where is order ORD-1042?");
console.log(result.finalOutput);Validate authorization, rate limits, tenancy, and side effects in the function itself. Instructions are guidance, not a security boundary. Prefer separate tools such as draft_refund and submit_refund over one “manage refunds” function. Require explicit human approval before irreversible actions.
Rank #2
Tool categories
- Read tools: fetch narrowly filtered records and return only fields the agent needs.
- Write tools: change state; require authorization, idempotency, and often approval.
- Hosted tools: provider-managed capabilities; verify data handling and availability before depending on them.
- MCP tools: capabilities exposed through the Model Context Protocol; treat each server as a separate trust and permission boundary.
- Agent-as-tool: a specialist exposed as a callable capability to a manager agent.
Return reliable structured data
When another part of your application consumes the result, prose is the wrong contract. Declare an output schema with Zod or another supported Standard Schema value. The SDK can use the schema for structured output and local validation. Reject invalid output, report a recoverable error, and avoid silently coercing a missing field into a dangerous default.
const triage = new Agent({
name: "Ticket triage",
instructions: "Classify the ticket and recommend the next queue.",
outputType: z.object({
category: z.enum(["billing", "technical", "account"]),
priority: z.enum(["low", "normal", "urgent"]),
rationale: z.string(),
}),
});Choose state deliberately
One-turn requests
Begin without a persistence system. Pass the necessary context in the request, run the agent, and discard run-local state. This keeps failure recovery and privacy simpler.
Conversation continuity
For a chat experience, decide where conversation history lives. Application-owned storage gives you control over retention, tenancy, redaction, and migration. Provider conversation state can reduce implementation work but moves part of the lifecycle and data policy to the provider. Define truncation, deletion, export, and replay behavior before launch.
Long-running work
Jobs that outlive an HTTP request need a durable job record, idempotent tool operations, retry limits, cancellation, and a resume strategy. Store checkpoints after meaningful steps rather than assuming a process will remain alive. Never retry a non-idempotent write without a request key or an application-level deduplication check.
Single agent, manager, or handoff?
One focused agent
Use one agent when the task has a coherent policy and a small tool set. This is the easiest shape to test: vary the user request, tool results, missing data, and refusal conditions.
Manager with specialists as tools
A manager remains responsible for the user-facing answer and calls specialists for bounded expertise. This works when one central policy must reconcile outputs—for example, a support manager calling billing and technical specialists. The manager controls the final response, but you must define timeouts, conflicting recommendations, and maximum delegation depth.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Handoff
A handoff transfers conversational ownership to a specialist. Use it when the specialist should directly conduct the next part of the interaction, such as transferring a billing conversation to a billing agent. Make the transfer condition explicit and preserve the context the specialist needs.
Multi-agent is not automatically more capable. It adds coordination, state, tracing, cost, and failure modes. Add specialists when their separate authority or instructions produce a measurable product benefit.
Runtime and framework choices
The OpenAI Agents SDK repository lists Node.js 22 or later, Deno, and Bun, with Cloudflare Workers identified as experimental support. Confirm the current matrix at build time because runtime support and package APIs change. The SDK is an application-run loop: your server owns deployment, tools, storage, and approvals. A managed Agents API uses a service-managed harness instead, changing where execution and operational responsibilities live.
Vercel describes AI SDK Core as a unified interface for text generation, structured objects, tool calls, and agents, with AI SDK UI providing framework-agnostic chat and generative-UI hooks. Its 17 June 2026 guide also describes Gateway, Sandbox, Chat SDK, Connect, and Workflow as surrounding services for model routing, isolated execution, delivery, scoped third-party access, and durable runs. Treat those descriptions as product capabilities to verify, not timeless guarantees.
Rank #4
Compare frameworks against your workload
| Question | Why it matters |
|---|---|
| Provider and model fit | Confirm required providers, transports, model availability, and how easily you can switch. |
| Control boundary | Identify who runs the loop, executes tools, stores state, and approves actions. |
| Tool integration | Check local functions, hosted tools, MCP, schemas, permissions, and error handling. |
| Workflow shape | Ensure support for single agents, manager composition, handoffs, or code-driven graphs. |
| Durability | Check resume, retries, cancellation, conversation continuity, and application persistence. |
| Safety | Look for input/output checks, human review, sandbox isolation, rollback, and audit logs. |
| Developer experience | Evaluate TypeScript types, structured outputs, tracing, debugging, and workflow tests. |
| Delivery | Match streaming, UI framework, runtime, deployment, and observability requirements. |
Streaming, approvals, and isolation
For a user-facing interface, stream progress only after deciding which events are safe to reveal. Tool arguments may contain secrets; filter them before sending events to the browser. Represent approval as an explicit state—awaiting_approval—rather than a prompt convention that can be bypassed.
Filesystem and command execution deserve isolation. The Agents SDK README recommends a sandbox agent for this class of work. Use a restricted filesystem, network policy, CPU and memory limits, timeouts, and a disposable identity. A tool that can execute arbitrary commands is not equivalent to a normal business function.
Or skip the browser setup: capture agent-friendly screenshots
If your agent needs a visual snapshot of a web page, ScreenshotNeo provides a single website-screenshot API and an MCP server. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; you can turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing result in X-Page-Verdict and X-Billed headers.
Use the documented call from your server:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());See the ScreenshotNeo documentation for the full parameter set. The service supports full-page and element captures, device presets and custom viewports, dark mode, retina scale, PDF output, HTML/CSS rendering, custom JavaScript and CSS, clicks, waits, blocked resources, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. It also accepts parameter names used by other screenshot APIs, easing migration.
An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. Pricing is Free for 1,000 shots per month with no card; Starter is $5 for 3,000; Growth $15 for 15,000; Pro $39 for 60,000; Scale $99 for 250,000; and Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. Create a free ScreenshotNeo account to get the 1,000 monthly screenshots without a card.
Troubleshooting common failures
The agent loops or calls a tool repeatedly
Inspect the run history. Tighten the tool description, return a clear terminal result, cap turns, and add an application-side loop limit. If the same arguments repeat, fail safely and request human review.
Arguments fail validation
Return the schema error during development, then improve the description and examples. Keep coercion explicit; do not accept arbitrary objects just to make the error disappear.
The answer invents missing facts
Tell the agent to say when required data is absent, make the read tool authoritative, and test empty, stale, and contradictory results. Structured output can force a missing-data state instead of allowing a confident paragraph.
Recommended Free Tools
A tool succeeds twice after a retry
Make writes idempotent with a request key, record completion before acknowledging success, and distinguish timeout-after-commit from timeout-before-commit.
Browser or screenshot capture is blank
Check the response verdict and billing headers, wait for a meaningful selector or network idle, increase the timeout only when necessary, and verify that authentication cookies or headers are present. A bot check, failed load, or blank page should be handled as an unavailable observation rather than passed to the model as if it were valid.
Testing and operating an agent
- Test normal requests, missing fields, malformed tool arguments, authorization failures, timeouts, provider errors, and contradictory tool results.
- Evaluate end-to-end outcomes, not only whether the model selected the expected tool.
- Track latency by model call and tool call, token usage, retries, approval waits, and terminal outcomes.
- Redact secrets and personal data from traces; set retention and deletion rules.
- Use feature flags and canary traffic when changing prompts, schemas, models, or tool permissions.
- Set budgets for turns, tokens, wall-clock time, and external calls.
A practical build sequence
- Write the outcome, authority boundaries, and approval policy.
- Implement one server-side agent with no tools and verify the request path.
- Add one read-only tool with a strict schema and authorization checks.
- Add structured output if downstream code consumes the result.
- Instrument run history, errors, latency, and redacted tool events.
- Add persistence only for a demonstrated continuity or durability requirement.
- Introduce specialists through manager tools or handoffs only after the single-agent case is reliable.
- Isolate filesystem, command, or untrusted-code work in a sandbox.
- Load-test tool dependencies and test retries, cancellation, and duplicate writes.
Frequently Asked Questions
Should every chatbot be an agent?
No. Use a deterministic function or single model call when there is no meaningful tool choice or iterative decision.
Can an agent call a browser from client-side JavaScript?
Keep privileged browsing and provider credentials on your server. Expose only a controlled API or an MCP connection with explicit permissions.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →When should I split one agent into specialists?
Split when domains have materially different instructions, tools, data permissions, or approval policies; otherwise the added coordination may not justify itself.
What is the safest first tool?
A read-only function with validated parameters, tenant-aware authorization, bounded output, and no irreversible side effects.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
