> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galileo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agent Integration

> Get hands on integrating Galileo into an agentic app using the OpenAI Agents SDK

{/*<!-- markdownlint-enable MD044 -->*/}

Follow this step-by-step guide to build a "Homework Assistant" AI agent pipeline using **Galileo's OpenAI integrations**.

## OpenAI Agent walkthrough

<Steps>
  <Step title="Create Project Folder">
    Create a new project folder and navigate to it in your terminal.

    <CodeGroup>
      ```python Python theme={null}
      mkdir homework-assistant
      cd homework-assistant
      ```
    </CodeGroup>
  </Step>

  <Step title="Install Dependencies">
    Install the **Galileo SDK** and other necessary dependencies using the following command in your terminal.

    <CodeGroup>
      ```bash Python theme={null}
      pip install galileo openai-agents python-dotenv
      ```
    </CodeGroup>
  </Step>

  <Step title="Create Project Files">
    In your project folder, create a new blank application file and `.env` file.

    <CodeGroup>
      ```python Python theme={null}
      homework-assistant/
      │── app.py
      │── .env
      ```
    </CodeGroup>
  </Step>

  <Step title="Set Environment Variables">
    In your `.env` file, set your environment variables by filling in your API keys, Project name, and Log stream name.

    By using these exact variable names, Galileo will **automatically use them** in your application.

    <CodeGroup>
      ```ini .env theme={null}
      GALILEO_PROJECT="Homework Assistant"
      GALILEO_LOG_STREAM="batch-1"
      GALILEO_API_KEY="your-Galileo-api-key-here"

      # Provide the console url below if you are using a
      # custom deployment, and not using the free tier, or app.galileo.ai.
      # This will look something like “console.galileo.yourcompany.com”.
      # GALILEO_CONSOLE_URL=your-galileo-console-url

      OPENAI_API_KEY="your-OpenAI-api-key-here"
      ```
    </CodeGroup>

    * **NOTE:** The Project name and Log stream name are customizable. Change them as needed for your own experiments. You can view all your Projects and Log streams in the [Galileo Console](https://app.galileo.ai).
  </Step>

  <Step title="Import Libraries">
    In your application file, add the following code to import all required libraries.

    <CodeGroup>
      ```python Python theme={null}
      from galileo.handlers.openai_agents import GalileoTracingProcessor
      from agents import (
          set_trace_processors,
          Agent,
          GuardrailFunctionOutput,
          InputGuardrail,
          Runner
      )
      from pydantic import BaseModel
      import asyncio
      from dotenv import load_dotenv
      load_dotenv()
      ```
    </CodeGroup>
  </Step>

  <Step title="Define Output Structure">
    Add the code below to your application file to define an output structure.

    The Guardrail agent uses this structure to **reject invalid outputs by type**. For example, an `int` would be an invalid output in response to the question "Who was the first president of the United States?"

    This is achieved in **Python** using `BaseModel`.

    * **BaseModel:** A **Python** class from the `pydantic` library which automatically validates whether groups of values are the correct types.

    <CodeGroup>
      ```python Python theme={null}
      # Create a class with BaseModel to validate output types
      class HomeworkOutput(BaseModel):
          is_homework: bool
          reasoning: str
      ```
    </CodeGroup>
  </Step>

  <Step title="Create Tutor Agents">
    Add the code below to your application file to create **two specialized "tutor agents"**. One handles math questions, and the other handles history.

    * **Agent**: An AI module that receives inputs and provides specialized outputs based on predefined instructions.

    <CodeGroup>
      ```python Python theme={null}
      # Create math tutor agent to answer math questions
      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
          """,
      )

      # Create history tutor agent to answer history questions
      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.
          """,
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Create Guardrail Agent">
    Add the code below to your application file to set up a **Guardrail Agent** that will filter out non-homework questions.

    * **Guardrail Agent**: A specialized agent for evaluating inputs and determining whether they meet specific criteria.

    <CodeGroup>
      ```python Python theme={null}
      # Create Guardrail agent to determine if input question
      # is homework-related
      guardrail_agent = Agent(
          name="Guardrail check",
          instructions="Check if the user is asking about homework.",
          output_type=HomeworkOutput
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Define Guardrail Function">
    Add the code below to your application file to define the Guardrail Agent's logic for accepting valid inputs (in this case, homework questions) and rejecting invalid ones.

    * **Tripwire**: A condition that triggers if the guardrail criteria are not met, preventing further processing.

    <CodeGroup>
      ```python Python theme={null}
      # Set tripwire to filter out non-homework questions with Guardrail agent
      async def homework_guardrail(ctx, agent, input_data):
          result = await Runner.run(guardrail_agent,
                                    input_data,
                                    context=ctx.context)
          final_output = result.final_output_as(HomeworkOutput)
          return GuardrailFunctionOutput(output_info=final_output,
              tripwire_triggered=not final_output.is_homework)
      ```
    </CodeGroup>
  </Step>

  <Step title="Create Triage Agent">
    Add the code below to your application file to set up a **Triage Agent** to pass the input question to the appropriate tutor agent.

    * **Triage Agent**: An agent that analyzes the input and determines which specialized agent should handle the request.

    <CodeGroup>
      ```python Python theme={null}
      # Create Triage agent to determine which tutor agent to use
      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)
          ],
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Run the Agents">
    Add the code below to your application file. It **runs the complete system** by sending sample inputs and observing which agents handles the questions.

    This code also sets a custom [OpenAI trace processor](https://openai.github.io/openai-agents-python/tracing/#custom-tracing-processors). This call replaces the built in OpenAI trace processor with a Galileo one that logs traces to Galileo.

    To learn more, check out the [Python `GalileoTracingProcessor` SDK docs](/sdk-api/python/reference/handlers/openai_agents#galileotracingprocessor-objects).

    * **Runner**: A utility that executes the agents with provided input and context.

    <CodeGroup>
      ```python Python theme={null}
      # Use the Runner to run the agents and get the answers
      async def main():
          # Set the trace processor to the Galileo trace processor
          set_trace_processors([GalileoTracingProcessor()])

          result = await Runner.run(triage_agent,
              "who was the first president of the united states?")
          print(result.final_output)

          result = await Runner.run(triage_agent, "what is life?")
          print(result.final_output)

      if __name__ == "__main__":
          asyncio.run(main())
      ```
    </CodeGroup>
  </Step>

  <Step title="Complete Application Code">
    Below is the **final combined code** for the "Homework Assistant" AI agent application. Review it and compare it with your code.

    <CodeGroup>
      ```python Python theme={null}
      from galileo.handlers.openai_agents import GalileoTracingProcessor
      from agents import (
          set_trace_processors,
          Agent,
          GuardrailFunctionOutput,
          InputGuardrail,
          Runner
      )
      from pydantic import BaseModel
      import asyncio
      from dotenv import load_dotenv
      load_dotenv()

      # Create a class with BaseModel to validate output types
      class HomeworkOutput(BaseModel):
          is_homework: bool
          reasoning: str

      # Create math tutor agent to answer math questions
      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
          """,
      )

      # Create history tutor agent to answer history questions
      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.
          """,
      )

      # Create Guardrail agent to determine if input question
      # is homework-related
      guardrail_agent = Agent(
          name="Guardrail check",
          instructions="Check if the user is asking about homework.",
          output_type=HomeworkOutput
      )

      # Set tripwire to filter out non-homework questions with Guardrail agent
      async def homework_guardrail(ctx, agent, input_data):
          result = await Runner.run(guardrail_agent,
                                    input_data,
                                    context=ctx.context)
          final_output = result.final_output_as(HomeworkOutput)
          return GuardrailFunctionOutput(output_info=final_output,
              tripwire_triggered=not final_output.is_homework)

      # Create Triage agent to determine which tutor agent to use
      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)
          ],
      )

      # Use the Runner to run the agents and get the answers
      async def main():
          # Set the trace processor to the Galileo trace processor
          set_trace_processors([GalileoTracingProcessor()])

          result = await Runner.run(triage_agent,
              "who was the first president of the united states?")
          print(result.final_output)

          result = await Runner.run(triage_agent, "what is life?")
          print(result.final_output)

      if __name__ == "__main__":
          asyncio.run(main())
      ```
    </CodeGroup>
  </Step>

  <Step title="Open project & Log stream">
    In your browser, open the [Galileo Console](https://app.galileo.ai). Then, select the Project and Log stream whose names you used in your `.env` file.

    You will see new Traces, each containing data logged from running your AI Agent pipeline.

    * **NOTE:** Learn more about using **Projects** and **Log streams** in the [Getting Started Guide](/getting-started/quickstart).

          <img src="https://mintcdn.com/v2galileo/TWxseXCnsfLU-YxX/images/console-ui/openai-agent-log-stream.PNG?fit=max&auto=format&n=TWxseXCnsfLU-YxX&q=85&s=fb844e61aeaff86d023edf6d266f6389" alt="Log stream" width="1920" height="537" data-path="images/console-ui/openai-agent-log-stream.PNG" />
  </Step>

  <Step title="View Results">
    In the [Galileo Console](https://app.galileo.ai), click on one of the new Trace entries to see all of the data and steps executed by running your "Homework Assistant" application.

    You should see:

    * Each agent involved and when it was used
    * All agent inputs, outputs, and handoffs
    * Whether Guardrail Tripwires were passed or triggered
    * The time of execution, Project ID, Run ID, Trace ID, and Parent ID (viewable in the "Parameters" tab in the top-right)

          <img src="https://mintcdn.com/v2galileo/TWxseXCnsfLU-YxX/images/console-ui/openai-agent-trace.PNG?fit=max&auto=format&n=TWxseXCnsfLU-YxX&q=85&s=0eecf0beda470cc65f5d5f6e5a1614eb" alt="View Trace" width="1916" height="853" data-path="images/console-ui/openai-agent-trace.PNG" />
  </Step>

  <Step title="OPTIONAL: Test the Guardrail Tripwire">
    To see the Tripwire get triggered, modify one of the inputs to be a question that is **not** about homework.

    * **NOTE:** This will **cause an error** because the Guardrail Agent rejects questions that trigger the Tripwire.

    <CodeGroup>
      ```python Python theme={null}
      # Input is changed to non-homework question
      async def main():
          result = await Runner.run(triage_agent, "What is the meaning of life?")
          print(result.final_output)
      ```
    </CodeGroup>
  </Step>

  <Step title="Congratulations!">
    Your OpenAI Agent Pipeline is complete and ready to use.
  </Step>
</Steps>

***

## Next steps

* Create your own project with new `instructions` to define **your own specialized agents**.
* Include [Metadata](/concepts/annotations) and [Tags](/concepts/annotations) in your logs to track results and add automations.
* Add [Metrics](/concepts/metrics) to your experiment to evaluate results.
* Create [Datasets](/sdk-api/experiments/datasets) to improve evaluation accuracy and compare performance improvements.