
How-Tos
How to run a first OpenAI Agents SDK agent
Official OpenAI Agents SDK quickstart for installing the SDK and running one history-tutor agent in JavaScript or Python.
Use the Agents SDK quickstart when you want the shortest path to a working SDK-based agent. The examples use the same high-level concepts in JavaScript and Python: define an agent, run it, then add tools and specialist agents as the workflow grows.
This walkthrough stops at that first working loop. Install the SDK, set the API key, define one history-tutor agent, and make one run call. Add tools and specialist agents only after that single-turn loop works, and keep the same shape rather than starting with a large multi-agent design.
Install the SDK and set the key
Create a project, install the SDK, and set your API key. The quickstart puts both languages and the key export in one block:
# JavaScript
npm install @openai/agents zod
# Python
pip install openai-agents
export OPENAI_API_KEY=sk-...
The hash lines are comments. Run the install line for the language you are using, then the export line. Do not drop a package the JavaScript install includes, and do not add a flag the page never shows. The first-agent snippets do not say why the second JavaScript package is there. Leave the install line as written.
The export line sets the API key variable. The value in the snippet is the placeholder shown after the equals sign. Set that variable to your own key before you run the example.
The page labels the key step Create an API Key and does not describe the creation steps, so this article does not invent them. It also does not show a project scaffold, a virtual environment, or a filename. Use your usual project setup, install as shown, and export the key first.
Run one history tutor in JavaScript
Start with one focused agent and one turn. The SDK handles the model call and returns a result object with the final output plus the run history.
import { Agent, run } from "@openai/agents";
const agent = new Agent({
name: "History tutor",
instructions: "You answer history questions clearly and concisely.",
model: "gpt-6-astra",
});
const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);
The import line brings in Agent and the run function. The constructor takes a name, instructions, and a model. In this example the name is History tutor, the instructions ask for clear and concise history answers, and the model is the string in the snippet. The quickstart does not define that model further on this page. Use the string the example shows.
The run call takes the agent and one user message: When did the Roman Empire fall? The call is awaited. The snippet then prints result.finalOutput. The quickstart shows that await at the top level and does not wrap the JavaScript example in an async function.
Run the same agent in Python
The Python example is the same tutor, the same instructions, the same model, and the same question.
import asyncio
from agents import Agent, Runner
agent = Agent(
name="History tutor",
instructions="You answer history questions clearly and concisely.",
model="gpt-6-astra",
)
async def main() -> None:
result = await Runner.run(agent, "When did the Roman Empire fall?")
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())
The pip package name and the import name are not the same string. Use the Python install line from the block above, and use the import line in the example: from agents import Agent, Runner. Both names are in the quickstart. Do not rename the import so it matches the pip package.
Python does not call a free function named run. The awaited call is the Runner.run line inside the async main function in the snippet. The file starts that coroutine with asyncio.run(main()) when it is executed as a script. The printed field is result.final_output. The underscore is part of the Python name. JavaScript uses result.finalOutput. Mixing those two names is a good way to print nothing useful.
What a successful first run looks like
You should see a concise answer in the terminal. The page does not include a sample answer, so do not hunt for a particular sentence about the Roman Empire. Success is a printed final output from that one call.
The same result object is also how the quickstart says you decide what a second turn should use as state. You do not need a second turn to finish the first run. If you continue, the page’s table says to start with one of these:
- Keep the full history in your application with
result.historyin TypeScript orresult.to_input_list()in Python. - Let the SDK load and save history for you with a session.
- Let OpenAI manage continuation state with a server-managed continuation ID.
- Resume a run that paused for approval or interruption with
result.statein TypeScript orresult.to_state()in Python, together withinterruptions.
After handoffs, reuse lastAgent in TypeScript or last_agent in Python for the next turn when that specialist should stay in control. The first example has no handoff, so that field is not part of proving the loop.
The table names those options. It does not show session setup, a continuation-ID format, or resume code. Do not fill those in from memory.
Add tools only after the loop works
Once that loop works, keep the same shape and add capabilities incrementally rather than starting with a large multi-agent design.
The first capability the page adds is often a function tool, or a hosted OpenAI tool such as web search or file search. A later section splits homework into specialists and lets a router delegate with handoffs: a history tutor, a math tutor, and a triage agent. Those sections are the growth path. They are not the first run, and this guide does not reproduce them.
Tracing is already part of the normal server-side SDK path. As soon as the first run works, the quickstart says to open the Traces dashboard and inspect model calls, tool calls, handoffs, and guardrails before you start tuning prompts. On this first agent there are no tools and no handoffs, so the early check is the model call itself.
After the history tutor prints, the page points to the guide that matches the next capability you want: agent definitions, using tools, running agents, or orchestration and handoffs. Shape one specialist cleanly before you scale the workflow.
Run the history-tutor example in one language until the terminal prints a concise answer. Read that answer from result.finalOutput in JavaScript or result.final_output in Python. Keep the agent to the name, instructions, and model in the snippet, and keep the call to the single run shown there. When that loop is reliable, go back to the official quickstart linked below and take only the next section you actually need.
Sources
- Agents SDK quickstart developers.openai.com