Repository Public
1# Quickstart23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Use this page when you want the shortest path to a working SDK-based agent. The examples below use the same high-level concepts in both JavaScript and Python: define an agent, run it, then add tools and specialist agents as your workflow grows.67## Install the SDK89Create a project, install the SDK, and set your API key.10111213Create an API Key14151617181920```bash21# JavaScript22npm install @openai/agents zod2324# Python25pip install openai-agents2627export OPENAI_API_KEY=sk-...28```2930## Create and run your first agent3132Start 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.3334Create and run an agent3536```javascript37import { Agent, run } from "@openai/agents";3839const agent = new Agent({40 name: "History tutor",41 instructions: "You answer history questions clearly and concisely.",42 model: "gpt-6-astra",43});4445const result = await run(agent, "When did the Roman Empire fall?");46console.log(result.finalOutput);47```4849```python50import asyncio5152from agents import Agent, Runner5354agent = Agent(55 name="History tutor",56 instructions="You answer history questions clearly and concisely.",57 model="gpt-6-astra",58)596061async def main() -> None:62 result = await Runner.run(agent, "When did the Roman Empire fall?")63 print(result.final_output)646566if __name__ == "__main__":67 asyncio.run(main())68```697071You should see a concise answer in the terminal. Once that loop works, keep the same shape and add capabilities incrementally rather than starting with a large multi-agent design.7273## Carry state into the next turn7475The first run result is also how you decide what the second turn should use as state.7677| If you want | Start with |78| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |79| Keep the full history in your application | `result.history` in TypeScript or `result.to_input_list()` in Python |80| Let the SDK load and save history for you | A session |81| Let OpenAI manage continuation state | A server-managed continuation ID |82| Resume a run that paused for approval or interruption | `result.state` in TypeScript or `result.to_state()` in Python, together with `interruptions` |8384After handoffs, reuse `lastAgent` in TypeScript or `last_agent` in Python for the next turn when that specialist should stay in control.8586## Give the agent a tool8788The first capability you add is often a function tool or a hosted OpenAI tool such as web search or file search.8990Add a function tool9192```javascript93import { Agent, run, tool } from "@openai/agents";94import { z } from "zod";9596const historyFunFact = tool({97 name: "history_fun_fact",98 description: "Return a short history fact.",99 parameters: z.object({}),100 async execute() {101 return "Sharks are older than trees.";102 },103});104105const agent = new Agent({106 name: "History tutor",107 instructions:108 "Answer history questions clearly. Use history_fun_fact when it helps.",109 tools: [historyFunFact],110});111112const result = await run(113 agent,114 "Tell me something surprising about ancient life on Earth."115);116117console.log(result.finalOutput);118```119120```python121import asyncio122123from agents import Agent, Runner, function_tool124125126@function_tool127def history_fun_fact() -> str:128 """Return a short history fact."""129 return "Sharks are older than trees."130131132agent = Agent(133 name="History tutor",134 instructions="Answer history questions clearly. Use history_fun_fact when it helps.",135 tools=[history_fun_fact],136)137138139async def main() -> None:140 result = await Runner.run(141 agent,142 "Tell me something surprising about ancient life on Earth.",143 )144 print(result.final_output)145146147if __name__ == "__main__":148 asyncio.run(main())149```150151152Use the shared [Using tools](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk) guide when you need hosted tools, tool search, or agents-as-tools.153154## Add specialist agents155156A common next step is to split the workflow into specialists and let a router delegate to them with handoffs.157158Route to specialist agents159160```javascript161import { Agent, run } from "@openai/agents";162163const historyTutor = new Agent({164 name: "History tutor",165 instructions: "Answer history questions clearly and concisely.",166});167168const mathTutor = new Agent({169 name: "Math tutor",170 instructions: "Explain math step by step and include worked examples.",171});172173const triageAgent = Agent.create({174 name: "Homework triage",175 instructions: "Route each homework question to the right specialist.",176 handoffs: [historyTutor, mathTutor],177});178179const result = await run(180 triageAgent,181 "Who was the first president of the United States?"182);183184console.log(result.finalOutput);185console.log(result.lastAgent?.name);186```187188```python189import asyncio190191from agents import Agent, Runner192193history_tutor = Agent(194 name="History tutor",195 handoff_description="Specialist for history questions.",196 instructions="Answer history questions clearly and concisely.",197)198199math_tutor = Agent(200 name="Math tutor",201 handoff_description="Specialist for math questions.",202 instructions="Explain math step by step and include worked examples.",203)204205triage_agent = Agent(206 name="Homework triage",207 instructions="Route each homework question to the right specialist.",208 handoffs=[history_tutor, math_tutor],209)210211212async def main() -> None:213 result = await Runner.run(214 triage_agent,215 "Who was the first president of the United States?",216 )217 print(result.final_output)218 print(result.last_agent.name)219220221if __name__ == "__main__":222 asyncio.run(main())223```224225226## Inspect traces early227228The normal server-side SDK path includes tracing. As soon as the first run works, open the [Traces dashboard](https://platform.openai.com/traces) to inspect model calls, tool calls, handoffs, and guardrails before you start tuning prompts.229230## Next steps231232Once the first run works, continue with the guide that matches the next capability you want to add.233234235236 [Agent definitions237238239240 Shape one specialist cleanly before you scale the workflow.](https://developers.openai.com/api/docs/guides/agents/define-agents)241 [Using tools242243244245 Add hosted tools, function tools, and agents-as-tools.](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk)246 [Running agents247248249250 Learn the agent loop, streaming, and continuation strategies.](https://developers.openai.com/api/docs/guides/agents/running-agents)251 [Orchestration and handoffs252253254255 Decide when specialists should take over the conversation.](https://developers.openai.com/api/docs/guides/agents/orchestration)