Technical Explanation of examples-basic-lifecycle-example.py

This document provides a technical walkthrough of the examples-basic-lifecycle-example.py script. This script is an excellent example of how to use the agents library to create a multi-agent workflow, complete with custom tools and detailed lifecycle logging.

Core Components

The script is built around a few key components from the agents library:

1. Agents

Two distinct agents are defined:

• start_agent: This is the entry point of our agent workflow. Its instructions are to generate a random number. If the number is even, it should stop. If it's odd, it hands off the execution to the multiply_agent.
• multiply_agent: This agent's purpose is to take a number, multiply it by two, and return the final result.

2. Tools

The agents use two custom tools, defined using the @function_tool decorator:

• random_number(max: int) -> int: This function generates a random integer between 0 and the provided max value (inclusive).
• multiply_by_two(x: int) -> int: This function takes an integer x and returns its value multiplied by two.

3. Hooks

The script makes extensive use of hooks to provide detailed logging of the agent lifecycle. Two hook classes are defined:

• LoggingHooks: This class inherits from AgentHooks and implements the on_start and on_end methods to log the start and end of an agent's turn.
• ExampleHooks: This class inherits from RunHooks and provides a more detailed view of the entire run. It implements methods to log:
  • on_agent_start: When an agent starts.
  • on_llm_start and on_llm_end: When the underlying Large Language Model (LLM) is called and when it returns a response.
  • on_tool_start and on_tool_end: When a tool is invoked and when it completes.
  • on_handoff: When one agent hands off control to another.

Execution Flow

The main function kicks off the process:

1. It prompts the user for a maximum number.
2. It initializes a Runner with the start_agent.
3. The Runner begins execution, and the ExampleHooks start logging the process.

Let's trace the execution path based on the provided output:

1. The start_agent begins.
2. The LLM is invoked to determine the next step based on the agent's instructions.
3. The LLM decides to use the random_number tool.
4. The random_number tool is executed. In the example output, it generates an odd number (107).
5. The result of the tool is sent back to the LLM.
6. The LLM, following the start_agent's instructions, decides to hand off to the multiply_agent.
7. The multiply_agent starts.
8. The LLM is called again for the multiply_agent.
9. The LLM decides to use the multiply_by_two tool with the number received from the start_agent.
10. The multiply_by_two tool is executed, and the result (214) is returned.
11. The result is sent back to the LLM.
12. The LLM formats the final output according to the FinalResult Pydantic model.
13. The multiply_agent ends, and the final result is printed.

Output Analysis

The output file, examples-basic-lifecycle-example.py.txt, provides a clear, step-by-step log of the entire process. Each line, prefixed with ### <event_counter>, corresponds to a specific event in the agent lifecycle, logged by the ExampleHooks. The output shows the agent and LLM interactions, tool calls with their arguments, and the handoff between the start_agent and multiply_agent. The usage statistics (requests, input tokens, output tokens) are also logged at each step.

Conclusion

This example script is a powerful demonstration of the agents library's capabilities. It showcases how to:

• Define agents with specific instructions.
• Create and use custom tools.
• Implement agent handoffs for multi-step workflows.
• Use hooks for detailed logging and debugging.

By studying this example, developers can gain a solid understanding of how to build robust and observable agent-based applications.