This tutorial builds and runs one small AI agent with the OpenAI Agents SDK. You will install the Python package, provide an API key, define an agent with a focused instruction, send it one prompt, and inspect the run’s trace. The example is intentionally simple: it demonstrates an SDK run, not an autonomous system with tools or guaranteed behavior.
The worked example uses the Agents SDK, which runs in your application. OpenAI also documents a separate hosted Agents API route; its managed execution setup is not part of these SDK steps.
What you will build
You will make a small study-helper agent that explains a basic concept in plain language. It has no tools, does not browse the web, and cannot take actions outside the model request. That is a useful first milestone: you can confirm the SDK is installed, credentials are configured, and an agent can return a response before introducing extra moving parts.
The SDK’s runner handles the documented agent run flow. Tools extend what an agent can do; handoffs let a different, specialist agent take over. They are separate capabilities, and neither is needed for this first run.
PC 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 & 11Outdated 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 matchInstall the SDK and configure an API key
Choose one language for your project. The official quickstart lists these installation commands:
- Python:
pip install openai-agents - JavaScript:
npm install @openai/agents zod
You also need an OpenAI API key available to your application. Keep it out of source code, public repositories, screenshots, and logs. An environment variable is a common way to provide it; configure it in the shell or secret manager used to run your application. The examples below expect the SDK to find the key in its configured environment.
For Python, a virtual environment helps keep the project’s installed packages separate from other Python projects. Create and activate one using the method appropriate to your operating system, then run the install command in that environment. For JavaScript, run the install command from the project directory so the packages are recorded for that application.
Python: define an agent and run one prompt
Save this as first_agent.py after installing openai-agents:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
import asyncio
from agents import Agent, Runner
agent = Agent(
name="Study helper",
instructions=(
"Explain concepts clearly in plain language. "
"Keep answers concise and use one simple example when helpful."
),
)
async def main():
result = await Runner.run(
agent,
"In two sentences, explain what a Python list is."
)
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())Run it with python first_agent.py from the environment where the package and API key are available. The output should be a short explanation. The exact wording can vary between runs; treat it as an example response, not a fixed expected string.
The agent’s name identifies it in the run, while its instructions establish the task and style. Runner.run starts the request, and final_output is the final answer to print. If this minimal version fails, fix setup or credentials before adding tools.
JavaScript: the equivalent first run
If your project uses JavaScript, the official quickstart’s package installation includes both @openai/agents and zod. In a project configured to run ES modules, save the following as first-agent.js:
import { Agent, run } from "@openai/agents";
const agent = new Agent({
name: "Study helper",
instructions:
"Explain concepts clearly in plain language. " +
"Keep answers concise and use one simple example when helpful.",
});
const result = await run(
agent,
"In two sentences, explain what a Python list is."
);
console.log(result.finalOutput);Run it with your project’s JavaScript runtime after setting the API key in that process’s environment. As with Python, the response text is illustrative; the important first check is that the run completes and returns a final output.
Inspect the run before changing the prompt
After the first successful run, open the OpenAI Traces dashboard and inspect the trace. Traces are the recommended early debugging step because they can show model calls, tool calls, handoffs, and guardrails. This example only uses a model call, but the same inspection becomes more valuable once you add capabilities or route work between agents.
When a result is off-target, first check what the trace shows and then revise the instruction or prompt in a small, deliberate change. Avoid diagnosing a system you have not instrumented: an agent with tools can involve more steps than this single-response example.
Add tools or specialist agents only when needed
Use a tool when the agent needs an action or external information
A function tool can expose a specific operation from your application; a hosted tool can provide a supported capability outside your own function. Add the narrowest tool that satisfies the task, and define what inputs it accepts and what it is allowed to do. A plain-text instruction alone does not grant access to files, databases, or live information.
Use a handoff when another agent should take over
A handoff routes work to a different agent, such as a specialist for a distinct subject. The Python quickstart’s triage example routes homework questions to history or math specialists. The runner manages individual agents, tool calls, and handoffs in the documented flow. Do not add specialist agents just to make a basic response sound more autonomous; use them when routing changes who should handle the task.
Recommended Free Tools
Check execution results, not just the final turn
A completed turn does not, by itself, prove that every tool action succeeded. If your workflow depends on an action, inspect its execution result and trace, and handle failures explicitly in your application. Treat tool outputs as data your program must validate, not as proof that a real-world operation occurred successfully.
SDK or hosted Agents API?
These are two different implementation routes. Pick one based on where you want execution to happen, and do not combine their setup steps as though they described one SDK.
| Choice | Where it runs | When it fits | Important distinction |
|---|---|---|---|
| Agents SDK | In your application | A code-first integration where you define and run an agent in Python or JavaScript | Install the SDK package and use its runner; inspect the run in traces. |
| Agents API | In a managed harness in OpenAI’s service; the documented quickstart uses a hosted sandbox | A reader specifically exploring hosted execution | It is a separate path. A completed turn alone does not establish that every tool succeeded. |
This article’s code is for the SDK. If you want the hosted route, follow its own Agents API quickstart and sandbox instructions rather than adapting the SDK installation and runner code as if they were interchangeable.
Or skip the browser setup: capture a page for visual review
A screenshot API does not run an AI agent; it is an optional way to capture a page your application or team wants to inspect visually. ScreenshotNeo is a website screenshot API and MCP server. Its one-call endpoint can return an image or PDF, and its clean-shot workflow is useful when cookie banners or overlays would obscure a capture. The service says clean shots are billed, while bot checks, blank pages, timeouts, failed loads, and cache hits are not. Its MCP server provides screenshot tools for AI-agent clients, but that is separate from the SDK agent built above.
For example, capture a page as WebP with cURL:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://example.com
-o shot.webpSee the ScreenshotNeo API documentation for request details. ScreenshotNeo says cookie/consent banners, newsletter popups, and chat widgets can be removed before capture; each step can be turned off. It also offers an MCP server for AI agents, and the free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo, or sign up for the free plan.
Troubleshooting the first run
- Python reports that
agentscannot be imported: confirmopenai-agentswas installed in the same Python environment used to run the script. Activate the intended virtual environment and install the package there. - JavaScript cannot resolve
@openai/agents: install the listed packages from the project directory and run the script with the project’s configured module setup. - The request fails because credentials are missing or rejected: verify that the API key is set in the environment for the process running the script, and that it is valid. Do not paste it into the source file to work around the configuration issue.
- The script starts but returns an error rather than an answer: read the error and inspect the available trace or run details. Confirm network access and that the request is reaching the service before changing agent instructions.
- The answer is not the wording you expected: model responses can vary. Evaluate whether the instruction and prompt specify the actual constraints you care about; do not test success by requiring an exact sentence unless your application explicitly validates one.
- A future tool workflow appears to finish but did not accomplish the action: inspect the tool call and its result, then add application-level validation and failure handling. A final turn is not a substitute for checking action success.
Performance, reliability, and cost considerations
This example makes one model request and has no tool calls or handoffs. Adding tools or specialist routes adds work and additional failure points; keep the workflow as small as the task allows. For production use, decide how your application will handle request errors, timeouts, retries, and invalid or incomplete results instead of assuming every run returns a usable answer.
The documentation covered here does not establish a price for this example or a specific hardware requirement. Costs depend on the services and models used by the application, so check current platform pricing for the model and usage you choose. SDK package commands and documentation can change; verify the current official quickstart when upgrading or starting a new project.
Frequently Asked Questions
Does this example create an autonomous AI agent?
No. It runs one focused prompt and returns an answer; it has no tools or independent ongoing task loop.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Can I use the Agents API code with the SDK setup?
No. They are separate implementation paths with different execution arrangements.
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.
