docs: Document openai-agents control-flow

Author: alexander-alderman-webb

sentry_sdk/integrations/openai_agents/__init__.py

@@ -52,6 +52,18 @@ def _patch_tools() -> None:
 
 
 class OpenAIAgentsIntegration(Integration):
+    """
+    Typical interaction with the library:
+    1. The user creates an Agent instance with configuration, including system instructions sent to every Responses API call.
+    2. The user passes the agent instance to a Runner, which returns the agent execution response synchronously or asynchronously (the latter is called streaming).
+    3. In a loop, the agent repeatedly calls the Responses API, maintaining a conversation history that includes previous messages and tool results, which is passed to each call.
+
+    Local tools are run based on the return value from the Responses API as a post-API call step in the above loop.
+    Hosted MCP Tools are run as part of the Responses API call, and involve OpenAI reaching out to an external MCP server.
+    An agent can handoff to another agent, also directed by the return value of the Responses API and run post-API call in the loop.
+    Handoffs are a way to switch agent-wide configuration.
+    """
+
     identifier = "openai_agents"
 
     @staticmethod