Quickstart
Create a project and virtual environment
You'll only need to do this once.
Activate the virtual environment
Do this every time you start a new terminal session.
Install the Agents SDK
Set an OpenAI API key
If you don't have one, followthese instructions to create an OpenAI API key.
Create your first agent
Agents are defined with instructions, a name, and optional config (such asmodel_config)
fromagentsimportAgentagent=Agent(name="Math Tutor",instructions="You provide help with math problems. Explain your reasoning at each step and include examples",)Add a few more agents
Additional agents can be defined in the same way.handoff_descriptions provide additional context for determining handoff routing
fromagentsimportAgenthistory_tutor_agent=Agent(name="History Tutor",handoff_description="Specialist agent for historical questions",instructions="You provide assistance with historical queries. Explain important events and context clearly.",)math_tutor_agent=Agent(name="Math Tutor",handoff_description="Specialist agent for math questions",instructions="You provide help with math problems. Explain your reasoning at each step and include examples",)Define your handoffs
On each agent, you can define an inventory of outgoing handoff options that the agent can choose from to decide how to make progress on their task.
triage_agent=Agent(name="Triage Agent",instructions="You determine which agent to use based on the user's homework question",handoffs=[history_tutor_agent,math_tutor_agent])Run the agent orchestration
Let's check that the workflow runs and the triage agent correctly routes between the two specialist agents.
fromagentsimportRunnerasyncdefmain():result=awaitRunner.run(triage_agent,"What is the capital of France?")print(result.final_output)Add a guardrail
You can define custom guardrails to run on the input or output.
fromagentsimportGuardrailFunctionOutput,Agent,RunnerfrompydanticimportBaseModelclassHomeworkOutput(BaseModel):is_homework:boolreasoning:strguardrail_agent=Agent(name="Guardrail check",instructions="Check if the user is asking about homework.",output_type=HomeworkOutput,)asyncdefhomework_guardrail(ctx,agent,input_data):result=awaitRunner.run(guardrail_agent,input_data,context=ctx.context)final_output=result.final_output_as(HomeworkOutput)returnGuardrailFunctionOutput(output_info=final_output,tripwire_triggered=notfinal_output.is_homework,)Put it all together
Let's put it all together and run the entire workflow, using handoffs and the input guardrail.
fromagentsimportAgent,InputGuardrail,GuardrailFunctionOutput,Runnerfromagents.exceptionsimportInputGuardrailTripwireTriggeredfrompydanticimportBaseModelimportasyncioclassHomeworkOutput(BaseModel):is_homework:boolreasoning:strguardrail_agent=Agent(name="Guardrail check",instructions="Check if the user is asking about homework.",output_type=HomeworkOutput,)math_tutor_agent=Agent(name="Math Tutor",handoff_description="Specialist agent for math questions",instructions="You provide help with math problems. Explain your reasoning at each step and include examples",)history_tutor_agent=Agent(name="History Tutor",handoff_description="Specialist agent for historical questions",instructions="You provide assistance with historical queries. Explain important events and context clearly.",)asyncdefhomework_guardrail(ctx,agent,input_data):result=awaitRunner.run(guardrail_agent,input_data,context=ctx.context)final_output=result.final_output_as(HomeworkOutput)returnGuardrailFunctionOutput(output_info=final_output,tripwire_triggered=notfinal_output.is_homework,)triage_agent=Agent(name="Triage Agent",instructions="You determine which agent to use based on the user's homework question",handoffs=[history_tutor_agent,math_tutor_agent],input_guardrails=[InputGuardrail(guardrail_function=homework_guardrail),],)asyncdefmain():# Example 1: History questiontry:result=awaitRunner.run(triage_agent,"who was the first president of the united states?")print(result.final_output)exceptInputGuardrailTripwireTriggeredase:print("Guardrail blocked this input:",e)# Example 2: General/philosophical questiontry:result=awaitRunner.run(triage_agent,"What is the meaning of life?")print(result.final_output)exceptInputGuardrailTripwireTriggeredase:print("Guardrail blocked this input:",e)if__name__=="__main__":asyncio.run(main())View your traces
To review what happened during your agent run, navigate to theTrace viewer in the OpenAI Dashboard to view traces of your agent runs.
Next steps
Learn how to build more complex agentic flows:
- Learn about how to configureAgents.
- Learn aboutrunning agents.
- Learn abouttools,guardrails andmodels.