Shared from "Study" on Inkdown
This document compiles the best practices for using the OpenAI Agents Python SDK. These practices are distilled from real-world usage, community feedback, and the core development team's experience. Following these practices will help you build robust, maintainable, and efficient agent-based applications.
Begin with simple agents and add complexity gradually:
Build, test, and iterate quickly:
Always use type hints for better IDE support and type safety:
Write clear, specific agent instructions:
Test your agents extensively:
Each agent should have a single, clear responsibility:
Use descriptive agent names:
Match instructions to the agent's purpose:
Only include relevant tools:
Write clear handoff descriptions:
Use descriptive tool names:
Always use type hints:
Write clear docstrings:
Handle errors gracefully:
Validate inputs:
Use guardrails at the right level:
Make it clear when guardrails trigger:
Provide helpful output info:
Use parallel execution for independent checks:
Guardrails should handle their own errors:
Use different configs for different environments:
Store configuration in files:
Never hardcode sensitive data:
Validate configuration early:
Document configuration options:
Use dataclasses for context:
Keep context focused on relevant data:
Always use type hints:
Document context fields:
Avoid circular references in context:
Catch specific exceptions:
Include helpful context:
Log errors before re-raising:
Define custom error types:
Provide graceful fallbacks:
Always use async for production:
Set reasonable limits:
Choose the right model for the task:
Enable tracing when needed:
Use sessions to manage conversation history:
Validate all inputs:
Use guardrails for safety:
Require approval for sensitive operations:
Exclude sensitive data from traces:
Store secrets in environment variables:
Test all scenarios:
Use fixtures for common setup:
Mock external services:
Test edge cases:
Test with different configurations:
Document what each agent does:
Document tool behavior:
Document configuration options:
Document extension behavior:
Document public API:
Track key metrics:
Log important events:
Monitor performance metrics:
Alert on critical errors:
Use tracing for observability:
Use environment variables for configuration:
Handle graceful shutdown:
Implement health checks:
Set resource limits:
Implement rate limiting:
Following these best practices will help you:
Remember that best practices evolve with experience. Start with these guidelines, learn from your own experience, and adapt them to your specific use cases.