Add File Loading Utilities for Agent Instructions

[adhishthite]

PR Summary: Add File Loading Utilities for Agent Instructions

What Changed

• Added new file utility module (src/agents/extensions/file_utils.py) for safely loading instruction text files
• Created example demonstrating file-based instructions (examples/basic/file_instructions_example.py)
• Added sample instruction file (examples/basic/greet_instructions.txt) for the example
• Implemented comprehensive test suite (tests/test_file_utils.py) to verify all functionality
• Updated .gitignore to exclude AI assistant files (CLAUDE.md and .codex/)

Why the Changes Were Made

This PR introduces a secure way to load agent instructions from external files, enabling several important benefits:

• Improved Code Organization: Separates lengthy instruction text from code files
• Easier Content Editing: Instructions can be edited without modifying code
• Content Reuse: The same instruction file can be used across multiple agents
• Better Version Control: Text file changes can be tracked separately from code changes

Implementation Details

• The load_instructions_from_file() function provides robust validation:

  • Confirms file existence with clear error messaging
  • Restricts file extensions to safe types (.txt, .md)
  • Enforces size limits to prevent excessive memory usage
  • Handles encoding issues with proper exception hierarchy
  • Returns contents as a string ready for use in an Agent constructor

• The example demonstrates a complete workflow:

  • Loading instructions from a separate markdown file
  • Configuring an agent with the loaded instructions
  • Using Pydantic for structured output validation
  • Processing user input with file-based agent configuration

Impact on Codebase

This change enhances the library's flexibility by allowing developers to:

1. Store lengthy prompt instructions in dedicated files
2. Achieve cleaner separation between code and content
3. Enable non-technical team members to edit instructions without touching code
4. Better manage versioning of instruction content
5. Support larger, more complex instruction sets that would be unwieldy in code

[rm-openai]

@adhishthite generally looks good. Before I give it a more in-depth review, would love to hear your thoughts on whether this belongs in the SDK - it feels like it's easy to do in userland with instructions = open("file.txt", "r").read()?

[adhishthite]

@adhishthite generally looks good. Before I give it a more in-depth review, would love to hear your thoughts on whether this belongs in the SDK - it feels like it's easy to do in userland with instructions = open("file.txt", "r").read()?

You’re right that this could be done in userland, but I’d argue there’s value in having this small quality-of-life feature baked into the SDK for consistency and parity with other tools (ADK, PyDantic, etc) that support similar functionality out of the box. It helps reduce friction for new users and keeps the UX smooth. Happy to hear your thoughts if you feel strongly otherwise! @rm-openai