docs: Enhance core primitive documentation with Tracing and user-friendly definitions

docs/index.md

@@ -2,10 +2,11 @@
 
 The [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions. It's a production-ready upgrade of our previous experimentation for agents, [Swarm](https://github.com/openai/swarm/tree/main). The Agents SDK has a very small set of primitives:
 
--   **Agents**, which are LLMs equipped with instructions and tools
--   **Handoffs**, which allow agents to delegate to other agents for specific tasks
--   **Guardrails**, which enable the inputs to agents to be validated
--   **Sessions**, which automatically maintains conversation history across agent runs
+- **Agents**: These are large language models (LLMs) that are preconfigured with specific instructions, access to tools (like web search or file retrieval), and even safety guardrails. An agent's core function is to generate a response or decide which tool to use based on the current context.
+- **Handoffs**: This is one of the SDK’s most powerful features. It allows a primary agent to delegate a task to another, more specialized agent if the task falls outside its domain. This enables the creation of complex, multi-agent workflows.
+- **Guardrails**: These are built-in safety checks that validate both the inputs to the agent and its outputs. Their purpose is to ensure that agents operate within defined parameters, which is crucial for reducing risks associated with automation.
+- **Sessions**: This primitive automatically manages and maintains the conversation history across multiple agent runs. It ensures that the agent remembers previous interactions, providing a cohesive and contextual conversation flow without extra development effort.
+- **Tracing & Observability**: The SDK includes integrated tracing capabilities that allow developers to visualize and debug the flow of an agent’s actions in real-time. This is particularly useful for monitoring complex workflows, identifying performance bottlenecks, and optimizing the agent's behavior.
 
 In combination with Python, these primitives are powerful enough to express complex relationships between tools and agents, and allow you to build real-world applications without a steep learning curve. In addition, the SDK comes with built-in **tracing** that lets you visualize and debug your agentic flows, as well as evaluate them and even fine-tune models for your application.
 

docs/running_agents.md

@@ -128,8 +128,10 @@ You can use the Agents SDK [Temporal](https://temporal.io/) integration to run d
 
 The SDK raises exceptions in certain cases. The full list is in [`agents.exceptions`][]. As an overview:
 
--   [`AgentsException`][agents.exceptions.AgentsException] is the base class for all exceptions raised in the SDK.
--   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded] is raised when the run exceeds the `max_turns` passed to the run methods.
--   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError] is raised when the model produces invalid outputs, e.g. malformed JSON or using non-existent tools.
--   [`UserError`][agents.exceptions.UserError] is raised when you (the person writing code using the SDK) make an error using the SDK.
--   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered] is raised when a [guardrail](guardrails.md) is tripped.
+-   [`AgentsException`][agents.exceptions.AgentsException]: This is the base class for all exceptions raised within the SDK. It serves as a generic type from which all other specific exceptions are derived.
+-   [`MaxTurnsExceeded`][agents.exceptions.MaxTurnsExceeded]: This exception is raised when the agent's run exceeds the `max_turns` limit passed to the `Runner.run`, `Runner.run_sync`, or `Runner.run_streamed` methods. It indicates that the agent could not complete its task within the specified number of interaction turns.
+-   [`ModelBehaviorError`][agents.exceptions.ModelBehaviorError]: This exception occurs when the underlying model (LLM) produces unexpected or invalid outputs. This can include:
+    -   Malformed JSON: When the model provides a malformed JSON structure for tool calls or in its direct output, especially if a specific `output_type` is defined.
+    -   Unexpected tool-related failures: When the model fails to use tools in an expected manner
+-   [`UserError`][agents.exceptions.UserError]: This exception is raised when you (the person writing code using the SDK) make an error while using the SDK. This typically results from incorrect code implementation, invalid configuration, or misuse of the SDK's API.
+-   [`InputGuardrailTripwireTriggered`][agents.exceptions.InputGuardrailTripwireTriggered], [`OutputGuardrailTripwireTriggered`][agents.exceptions.OutputGuardrailTripwireTriggered]: This exception is raised when the conditions of an input guardrail or output guardrail are met, respectively. Input guardrails check incoming messages before processing, while output guardrails check the agent's final response before delivery.