Fix docs (#70)

Author: jasonyang101

agentex/docs/docs/api/adk.md

@@ -1,6 +1,11 @@
 # Agent Development Kit (ADK) Reference
 
-This is the API reference for the Agentex Python ADK. Use this ADK to leverage nice abstractions for interacting with the clients through Agentex's Agentic Infrastructure. This ADK makes things like streaming, tracing, tool calling, and communicating with clients in an async manner easy.
+!!! info "ADK vs SDK"
+    **ADK (Agent Development Kit)** - Use within agent code to interact with Agentex infrastructure (streaming, tracing, state management, etc.)
+
+    **SDK (Software Development Kit)** - Use to make requests to the Agentex server via its REST API. [View SDK Docs →](https://agentex-sdk.stldocs.app/api/python)
+
+This is the API reference for the Agentex Python ADK. Use this ADK to leverage convenient abstractions for interacting with clients through Agentex's Agentic Infrastructure. This ADK makes things like streaming, tracing, tool calling, and communicating with clients in an async manner easy.
 
 ## Agent Development Kit (ADK)
 

agentex/docs/docs/api/overview.md

@@ -2,9 +2,34 @@
 
 This section provides comprehensive reference documentation for all Agentex types, classes, and interfaces. Use this as your definitive guide to understanding the objects and APIs you'll work with when building agents.
 
+## Documentation Types
+
+Agentex provides three types of API documentation, each serving a different purpose:
+
+### Agentex REST API Reference
+**[View API Reference →](https://docs.gp.scale.com/reference/agentex/)**
+
+Complete REST API documentation for the Agentex server. Use this to understand the HTTP endpoints, request/response schemas, and authentication for interacting with Agentex from any programming language or external system.
+
+### Agentex SDK (Python Client)
+**[View SDK Client Docs →](https://agentex-sdk.stldocs.app/api/python)**
+
+Python client library for making requests to the Agentex server. Use this when you need to interact with Agentex via its REST API (create tasks, send messages, manage agents, etc.). The SDK wraps the REST API with convenient Python methods.
+
+**When to use:** Building applications or services that need to make requests to the Agentex server.
+
+### Agentex ADK (Agent Development Kit)
+**[View ADK Reference →](adk.md)**
+
+Python library for use **WITHIN** your agent code. The ADK provides high-level abstractions for streaming, tracing, tool calling, state management, and communicating with clients through Agentex's agentic infrastructure. It's specifically designed for agent development, not for making requests to the Agentex server.
+
+**When to use:** Building the internal logic of your agents.
+
+---
+
 ## What You'll Find
 
-- **[Agent Development Kit](adk.md)** - SDK reference specifically for agent development functionswith detailed function signatures
+- **[Agent Development Kit](adk.md)** - SDK reference specifically for agent development functions with detailed function signatures
 - **[Types](types.md)** - Complete API reference for all core data types (Task, TaskMessage, Event, ACP params, etc.)
 
 ## Core Object Categories

agentex/docs/docs/concepts/task.md

@@ -22,8 +22,6 @@ Think of a task like a chat session, customer support ticket, or workflow execut
 
 **Tasks maintain a flat ledger of messages.** This flat design is an intentional architectural decision that enables flexible multi-actor communication patterns.
 
-#### Why This Design?
-
 ```python
 # A single task's message ledger might include:
 messages = [
@@ -36,6 +34,8 @@ messages = [
 ]
 ```
 
+#### Why This Design?
+
 This flat structure allows:
 
 - **Multi-agent systems** where different agents contribute to the same conversation

agentex/docs/docs/index.md

@@ -20,6 +20,8 @@ The GitHub README will you how to scaffold an L1 example just to learn the ropes
 | Resource | Description |
 |----------|-------------|
 | **[Agentex README](https://github.com/scaleapi/scale-agentex#getting-started)** | **Getting Started**: Spin up a simple agent on your local computer from scratch in minutes. This comes with a full development UI and agent server. |
-| **[Python SDK](https://github.com/scaleapi/scale-agentex-python)** | **Examples**: Agent-building tutorials that work out of the box. These show how to build up from simple to more complex agents using Agentex. |
+| **[Python SDK Examples](https://github.com/scaleapi/scale-agentex-python)** | **Examples**: Agent-building tutorials that work out of the box. These show how to build up from simple to more complex agents using Agentex. |
+| **[API Reference](https://docs.gp.scale.com/reference/agentex/)** | **REST API**: Complete HTTP endpoint documentation for interacting with the Agentex server from any language or external system. |
+| **[SDK Client Docs](https://agentex-sdk.stldocs.app/api/python)** | **Python Client**: Python library for making requests to the Agentex server (create tasks, send messages, manage agents, etc.). |
 | **[Docs Site](https://agentex.sgp.scale.com/docs)** | **Concepts**: More in depth details on the what, why, and how of building L1-L5 agents.<br><br>**Enterprise Support**: Description of how our zero-ops deployment works. Learn how to share hundreds of agents with the rest of your company. Each agent is hosted and scaled independently on cloud-agnostic infrastructure. |