@@ -224,5 +224,4 @@ agent = Agent(llm=llm, tools=tools, condenser=condenser)
 
 ## Next Steps
 
-- **[LLM Metrics](/sdk/guides/llm-metrics)** - Track token usage reduction
-- **[Conversation Costs](/sdk/guides/conversation-costs)** - Analyze cost savings
+- **[LLM Metrics](/sdk/guides/metrics)** - Track token usage reduction and analyze cost savings
@@ -145,5 +145,5 @@ async def main():
 
 ## Next Steps
 
-- **[Persistence](/sdk/guides/persistence)** - Save and restore conversation state
-- **[Send Message While Processing](/sdk/guides/send-message-while-processing)** - Interrupt running agents
+- **[Persistence](/sdk/guides/convo-persistence)** - Save and restore conversation state
+- **[Send Message While Processing](/sdk/guides/convo-send-message-while-running)** - Interrupt running agents
@@ -142,5 +142,5 @@ conversation.run()
 
 ## Next Steps
 
-- **[Persistence](/sdk/guides/persistence)** - Save and restore conversation state
-- **[Send Message While Processing](/sdk/guides/send-message-while-processing)** - Interrupt running agents
+- **[Persistence](/sdk/guides/convo-persistence)** - Save and restore conversation state
+- **[Send Message While Processing](/sdk/guides/convo-send-message-while-running)** - Interrupt running agents
@@ -179,4 +179,4 @@ For the complete implementation details, see the [ConversationState class](https
 ## Next Steps
 
 - **[Pause and Resume](/sdk/guides/convo-pause-and-resume)** - Control execution flow
-- **[Async Operations](/sdk/guides/async)** - Non-blocking operations
+- **[Async Operations](/sdk/guides/convo-async)** - Non-blocking operations
@@ -194,4 +194,4 @@ The agent receives and incorporates the new message mid-execution, allowing for
 ## Next Steps
 
 - **[Pause and Resume](/sdk/guides/convo-pause-and-resume)** - Control execution flow
-- **[Async Operations](/sdk/guides/async)** - Non-blocking operations
+- **[Async Operations](/sdk/guides/convo-async)** - Non-blocking operations
@@ -17,7 +17,7 @@ tools = get_default_tools()
 agent = Agent(llm=llm, tools=tools)
 ```
 
-See [Tools Overview](/sdk/architecture/tools/overview) for the complete list of available tools.
+See [Tools Overview](/sdk/arch/tools/overview) for the complete list of available tools.
 
 ## Understanding the Tool System
 
@@ -27,7 +27,7 @@ The SDK's tool system is built around three core components:
 2. **Observation** - Defines output data (what the tool returns)
 3. **Executor** - Implements the tool's logic (what the tool does)
 
-These components are tied together by a **ToolDefinition** that registers the tool with the agent. For architectural details and advanced usage patterns, see [Tool System Architecture](/sdk/architecture/sdk/tool).
+These components are tied together by a **ToolDefinition** that registers the tool with the agent. For architectural details and advanced usage patterns, see [Tool System Architecture](/sdk/arch/sdk/tool).
 
 ## Creating a Custom Tool
 
 
@@ -66,7 +66,7 @@ Use the preset agent with common built-in tools:
 agent = get_default_agent(llm=llm, cli_mode=True)
 ```
 
-The default agent includes BashTool, FileEditorTool, etc. See [Tools Overview](/sdk/architecture/tools/overview) for the complete list of available tools.
+The default agent includes BashTool, FileEditorTool, etc. See [Tools Overview](/sdk/arch/tools/overview) for the complete list of available tools.
 
 ### Conversation
 Start a conversation to manage the agent's lifecycle:
@@ -99,4 +99,4 @@ FACTS.txt
 
 - **[Custom Tools](/sdk/guides/custom-tools)** - Create custom tools for specialized needs
 - **[Model Context Protocol (MCP)](/sdk/guides/mcp)** - Integrate external MCP servers
-- **[Security Analyzer](/sdk/guides/security-analyzer)** - Add security validation to tool usage
+- **[Security Analyzer](/sdk/guides/security)** - Add security validation to tool usage
@@ -149,4 +149,4 @@ Works with multimodal LLMs like GPT-4 Vision and Claude with vision capabilities
 ## Next Steps
 
 - **[Hello World](/sdk/guides/hello-world)** - Learn basic conversation patterns
-- **[Async Operations](/sdk/guides/async)** - Process multiple images concurrently
+- **[Async Operations](/sdk/guides/convo-async)** - Process multiple images concurrently
@@ -125,7 +125,7 @@ By registering a callback with your conversation, you can intercept and display
 This example is available on GitHub: [examples/01_standalone_sdk/23_responses_reasoning.py](https://github.com/All-Hands-AI/agent-sdk/blob/main/examples/01_standalone_sdk/23_responses_reasoning.py)
 </Note>
 
-OpenAI's latest models (e.g., GPT-5, GPT-5-Codex) support a [Responses API](Responses) that provides access to the model's reasoning process. By setting the `reasoning_effort` parameter, you can control how much reasoning the model performs and access those reasoning traces.
+OpenAI's latest models (e.g., GPT-5, GPT-5-Codex) support a [Responses API](https://platform.openai.com/docs/api-reference/responses) that provides access to the model's reasoning process. By setting the `reasoning_effort` parameter, you can control how much reasoning the model performs and access those reasoning traces.
 
 ```python icon="python" expandable examples/01_standalone_sdk/23_responses_reasoning.py
 """
@@ -252,6 +252,6 @@ The OpenAI Responses API provides reasoning traces that show how the model appro
 
 ## Next Steps
 
-- **[Interactive Terminal](/sdk/guides/interactive-terminal)** - Display reasoning in real-time
-- **[LLM Metrics](/sdk/guides/llm-metrics)** - Track token usage and performance
+- **[Interactive Terminal](/sdk/guides/agent-interactive-terminal)** - Display reasoning in real-time
+- **[LLM Metrics](/sdk/guides/metrics)** - Track token usage and performance
 - **[Custom Tools](/sdk/guides/custom-tools)** - Add specialized capabilities
@@ -133,4 +133,4 @@ llm = llm_registry.get("agent")
 ## Next Steps
 
 - **[LLM Routing](/sdk/guides/llm-routing)** - Automatically route to different models
-- **[LLM Metrics](/sdk/guides/llm-metrics)** - Track token usage and costs
+- **[LLM Metrics](/sdk/guides/metrics)** - Track token usage and costs