To build an AI agent in JavaScript, start with a model, clear instructions, and one or two narrowly scoped tools. The application—not the model—should implement those tools, validate their inputs, control permissions, store state, and decide when a person must approve an action. OpenAI’s JavaScript quickstart uses @openai/agents with zod to create an agent and run it; add specialists, persistence, and streaming only when the workflow calls for them.
What makes a JavaScript application an AI agent?
An agent is a model-driven workflow that can choose what to do next, often by requesting application tools. A regular model call receives input and returns output. An agent can interpret the task, select an allowed capability, use its result, and continue toward a response.
The tool boundary matters. A model can request a function such as looking up an order, but your application runs the function and determines its real effects. Keep each function narrowly scoped, validate its inputs, and restrict its access. The SDK documentation also covers hosted tools, MCP integrations, and agents exposed as tools. See the OpenAI Agents SDK guides.
- Use a deterministic function or a single model call when that already solves the problem.
- Use an agent when the model needs to choose among a limited set of capabilities or follow a variable sequence of steps.
- Require approval for consequential actions such as sending a payment, changing an account, or publishing content.
Build a first agent with JavaScript
The official OpenAI quickstart installs @openai/agents and zod. The following minimal example follows its documented interface. It assumes your project supports ES modules and has credentials configured server-side as required by the current SDK documentation.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
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);Install the documented packages with npm install @openai/agents zod. Before using this example in an application, confirm the current package and runtime guidance in the official Agents SDK documentation. The example has no account lookup tool yet, so it cannot actually retrieve order status; it demonstrates the agent setup and run call.
Define the task and its limits first
Write down the user outcome, the data the agent may use, the actions it may request, and what counts as a successful answer. Decide which actions require human approval. This prevents a broad instruction such as “manage customer accounts” from turning into an unclear, overpowered tool set.
Add a tool as a validated application function
Give each tool a clear name, a description that tells the model when to use it, a schema for its arguments, and an implementation with only the access it needs. For example, an order-status tool should accept an order identifier and retrieve only the authorized account’s order. The SDK supports Zod schemas for function tools; define the schema and function using the current tool guide, then attach that tool to the agent.
Do not treat a schema as authorization. Validate that the current user may access the requested record inside the tool implementation, and avoid accepting model-provided identifiers as proof of permission. Log tool calls and results appropriately, while excluding secrets and sensitive data you do not need to retain.
Recommended Free Tools
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Return structured data when prose is not enough
If another part of your application needs typed JSON rather than a free-form answer, define an output schema. The SDK guide documents an outputType option and local validation for Zod and supported Standard Schema values. Structured output can make downstream handling more predictable, but it does not establish that a value is true or that an action is safe: validate business rules separately.
Choose the JavaScript runtime and execution boundary
The OpenAI Agents SDK repository lists Node.js 22 or later, Deno, and Bun as supported environments, and identifies Cloudflare Workers with nodejs_compat as experimental support. These are volatile compatibility details, so check the current SDK repository before choosing a runtime or upgrading.
There are two distinct execution arrangements in OpenAI’s materials:
- Agents SDK: the agent loop runs within your application. Your team controls deployment, tool implementations, state storage, and approvals.
- Agents API: the harness is managed as a service. This changes where execution is handled; review the current documentation for the service’s behavior and requirements.
Running the loop in your application gives you direct integration control, along with responsibility for operating it. A managed harness moves part of that execution boundary to the service. Choose based on operational ownership, integration needs, and the controls your application requires; do not assume the two arrangements have identical state or deployment behavior.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Keep credentials on the server
Do not place a server API key in browser JavaScript. The SDK repository describes a different pattern for browser-based realtime clients: have your server create a short-lived ephemeral client token, then provide that token to the browser. Follow current realtime documentation for the token flow and permissions.
Choose a framework around the workload
There is no independent overall winner established by the reviewed official documentation. Compare approaches against a concrete task instead of choosing by feature count or the label “agent framework.”
| Decision axis | Questions to check |
|---|---|
| Model and provider fit | Does it support the providers and models you need, and can you change them without rewriting the application? |
| Control boundary | Who runs the loop, executes tools, stores state, and decides whether an action needs approval? |
| Tools and permissions | Can you use local functions, hosted tools, or MCP, and validate inputs while limiting tool authority? |
| Workflow shape | Does the task need one agent, a manager that calls specialists, a handoff, or explicit code-driven orchestration? |
| State and durability | How will you preserve conversation context, resume work, and handle long-running tasks? |
| Safety and review | What checks, approval points, isolation, and rollback mechanisms does the application need? |
| Developer experience | Are TypeScript types, structured outputs, tracing, debugging, and evaluation adequate for the team? |
| Interface and deployment | Do you need streaming UI hooks, a particular web framework, or a runtime with specific compatibility? |
OpenAI’s materials focus on its Agents SDK and managed Agents API. Vercel describes AI SDK Core as a unified API for text, structured objects, tool calls, and agents, and AI SDK UI as framework-agnostic chat and generative UI hooks. Its guide dated 17 June 2026 also describes AI Gateway, Sandbox, Chat SDK, Connect, and Workflow for model routing, isolated execution, platform delivery, scoped third-party access, and durable runs. Those descriptions are vendor product information, not an independent comparative test; confirm current availability, supported environments, and terms before depending on a capability. See Vercel AI SDK documentation and its Vercel product updates.
When to add state, specialists, or streaming
State for continuity
A one-turn task may not need persistence. If a user returns to an existing task or expects a continuing conversation, decide what state to keep and where. Application-owned storage gives your system control over retention and access; provider conversation state is another possible arrangement. OpenAI’s documentation distinguishes run-level conversation controls from agent constructor configuration. Check that distinction in the current SDK guide rather than assuming state is saved automatically.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Specialists for distinct responsibilities
Use multiple agents when separate instructions, tools, or authorities make the workflow easier to govern—not simply because a task seems complex. OpenAI documents two patterns:
- Manager with agents as tools: a central agent calls specialists and remains responsible for the response to the user.
- Handoff: the current agent delegates the conversation to a specialist, who takes over the delegated interaction.
Both add coordination and failure cases. Define what each agent may do, how its result is checked, and how the workflow responds when a specialist fails or returns incomplete information. Evaluate the end-to-end result, not just whether each agent can complete its isolated task.
Streaming for interactive interfaces
Streaming is a user-interface choice, not a requirement for every agent. It can show progress as a response is produced; the application still needs to handle tool activity, errors, cancellation, and any final structured result. Vercel’s AI SDK separates Core capabilities from UI hooks, which may suit teams that want a shared model-and-tool API alongside framework-oriented interface helpers. Confirm the current framework and runtime support before adopting it.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Reliability, safety, and operating costs
An agent can fail because a model response is incomplete, a tool errors, an external service is unavailable, or the requested action is unauthorized. Treat tool calls as untrusted requests and build recovery at the application boundary.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
- Set limits on tool permissions, execution time, and repeated attempts.
- Make actions that can have side effects idempotent where possible, and use an approval step for high-impact changes.
- Return clear tool errors the agent can respond to without exposing credentials or internal diagnostics.
- Persist only the state needed to resume work, and establish retention and access rules.
- Inspect runs and tool calls; the SDK materials describe guardrails, human review, and run inspection as available capabilities.
Agent workflows can make several model and tool calls for one user request, so measure the actual call pattern in your own application. The reviewed sources do not establish a universal cost or latency figure. Track usage, set application limits, and test failure handling with the providers and tools your deployment uses.
Troubleshooting common implementation problems
- Package or import errors: confirm that
@openai/agentsis installed, that the project’s module setup matches its imports, and that you are following the current SDK examples. - Runtime incompatibility: check the repository’s current support list. The listed Node.js baseline is 22 or later; Cloudflare Workers support is marked experimental.
- The agent invents a tool result: make sure the tool is attached and its description matches the task. Do not ask the model to infer live account or database data that only the application can retrieve.
- A tool receives malformed input: validate its schema and handle validation failures explicitly. Return a bounded error instead of allowing invalid values to reach a sensitive operation.
- It answers without asking for a required fact: make the missing-information rule explicit in instructions, and ensure the tool design does not let the agent bypass it.
- Conversation context disappears: verify whether the current run configuration supplies or retrieves prior conversation state. Add application persistence if the chosen arrangement does not meet continuity needs.
- Browser code exposes credentials: move server credentials out of the client. For realtime browser clients, follow the ephemeral-token approach documented by the SDK repository.
- A specialist loop becomes hard to debug: reduce the number of agents, clarify ownership and handoff conditions, and inspect the run sequence before adding more delegation.
Or skip the browser setup
If your agent needs to capture a web page, ScreenshotNeo provides a website screenshot API and MCP server. Its API returns PNG, JPEG, WebP, or PDF from one GET request. Cookie banners are accepted like a visitor and more than 60 known consent platforms, newsletter popups, and chat widgets can be removed before the shot; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
For example, with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpUse your API key and target URL in place of the example values. See the ScreenshotNeo API documentation for parameters and response details. The same API can be called from Python or Node.js:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo offers 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Every feature is on every plan. Sign up for 1,000 free screenshots a month, with no card required.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Can I write an AI agent in TypeScript?
Yes. The examples here use JavaScript syntax; check the current SDK documentation for TypeScript-specific types and examples.
Does an AI agent need multiple agents to be useful?
No. Start with one agent and add specialists only when distinct responsibilities or permissions justify the extra coordination.
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.
