done with llm and condenser

Author: xingyaoww

docs.json

@@ -181,20 +181,18 @@
           {
             "group": "Guides",
             "pages": [
+              "sdk/guides/hello-world",
+              "sdk/guides/custom-tools",
+              "sdk/guides/mcp",
+              "sdk/guides/activate-skill",
+              "sdk/guides/context-condenser",
               {
-                "group": "Getting Started",
-                "pages": [
-                  "sdk/guides/hello-world",
-                  "sdk/guides/custom-tools",
-                  "sdk/guides/mcp"
-                ]
-              },
-              {
-                "group": "Agent Configuration",
+                "group": "LLM Configuration",
                 "pages": [
                   "sdk/guides/llm-registry",
                   "sdk/guides/llm-routing",
-                  "sdk/guides/model-reasoning"
+                  "sdk/guides/llm-reasoning",
+                  "sdk/guides/llm-metrics"
                 ]
               },
               {
@@ -204,15 +202,12 @@
                   "sdk/guides/pause-and-resume",
                   "sdk/guides/confirmation-mode",
                   "sdk/guides/send-message-while-processing",
-                  "sdk/guides/conversation-costs",
-                  "sdk/guides/llm-metrics",
-                  "sdk/guides/context-condenser"
+                  "sdk/guides/conversation-costs"
                 ]
               },
               {
                 "group": "Agent Capabilities",
                 "pages": [
-                  "sdk/guides/activate-skill",
                   "sdk/guides/async",
                   "sdk/guides/planning-agent-workflow",
                   "sdk/guides/browser-use",

sdk/guides/activate-skill.mdx

@@ -1,5 +1,5 @@
 ---
-title: Skills
+title: Agent Skills
 description: Skills add specialized behaviors, domain knowledge, and context-aware triggers to your agent through structured prompts.
 ---
 
@@ -128,7 +128,7 @@ uv run python examples/01_standalone_sdk/03_activate_skill.py
 
 Skills are defined with a name, content (the instructions), and an optional trigger:
 
-```python highlight={2-5,8-10}
+```python highlight={3-14}
 agent_context = AgentContext(
     skills=[
         Skill(
@@ -151,7 +151,7 @@ agent_context = AgentContext(
 
 Use `KeywordTrigger` to activate skills only when specific words appear:
 
-```python highlight={3}
+```python highlight={4}
 Skill(
     name="magic-word",
     content="Special instructions when magic word is detected",
@@ -163,7 +163,7 @@ Skill(
 
 Add consistent prefixes or suffixes to system and user messages:
 
-```python highlight={2-3}
+```python highlight={3-4}
 agent_context = AgentContext(
     skills=[...],
     system_message_suffix="Always finish your response with the word 'yay!'",

sdk/guides/context-condenser.mdx

@@ -3,13 +3,59 @@ title: Context Condenser
 description: Manage agent memory by condensing conversation history to save tokens.
 ---
 
+## What is a Context Condenser?
+
+A **context condenser** is a crucial component that addresses one of the most persistent challenges in AI agent development: managing growing conversation context efficiently. As conversations with AI agents grow longer, the cumulative history leads to:
+
+- **💰 Increased API Costs**: More tokens in the context means higher costs per API call
+- **⏱️ Slower Response Times**: Larger contexts take longer to process
+- **📉 Reduced Effectiveness**: LLMs become less effective when dealing with excessive irrelevant information
+
+The context condenser solves this by intelligently summarizing older parts of the conversation while preserving essential information needed for the agent to continue working effectively.
+
+## Default Implementation: LLMSummarizingCondenser
+
+OpenHands SDK provides `LLMSummarizingCondenser` as the default condenser implementation. This condenser uses an LLM to generate summaries of conversation history when it exceeds the configured size limit.
+
+### How It Works
+
+When conversation history exceeds a defined threshold, the LLM-based condenser:
+
+1. **Keeps recent messages intact** - The most recent exchanges remain unchanged for immediate context
+2. **Preserves key information** - Important details like user goals, technical specifications, and critical files are retained
+3. **Summarizes older content** - Earlier parts of the conversation are condensed into concise summaries using LLM-generated summaries
+4. **Maintains continuity** - The agent retains awareness of past progress without processing every historical interaction
+
+![Condenser Overview](https://openhands.dev/assets/blog/20250409-oh-condenser-release/condenser-overview.png)
+
+
+This approach achieves remarkable efficiency gains:
+- Up to **2x reduction** in per-turn API costs
+- **Consistent response times** even in long sessions
+- **Equivalent or better performance** on software engineering tasks
+
+Learn more about the implementation and benchmarks in our [blog post on context condensation](https://openhands.dev/blog/openhands-context-condensensation-for-more-efficient-ai-agents).
+
+### Extensibility
+
+The `LLMSummarizingCondenser` extends the `RollingCondenser` base class, which provides a framework for condensers that work with rolling conversation history. You can create custom condensers by extending base classes ([source code](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)):
+
+- **`RollingCondenser`** - For condensers that apply condensation to rolling history
+- **`CondenserBase`** - For more specialized condensation strategies
+
+This architecture allows you to implement custom condensation logic tailored to your specific needs while leveraging the SDK's conversation management infrastructure.
+
+
+### Example Usage
+
 <Note>
 This example is available on GitHub: [examples/01_standalone_sdk/14_context_condenser.py](https://github.com/All-Hands-AI/agent-sdk/blob/main/examples/01_standalone_sdk/14_context_condenser.py)
 </Note>
 
+
 Automatically condense conversation history when context length exceeds limits, reducing token usage while preserving important information:
 
-```python icon="python" examples/01_standalone_sdk/14_context_condenser.py
+```python icon="python" expandable examples/01_standalone_sdk/14_context_condenser.py
 """
 To manage context in long-running conversations, the agent can use a context condenser
 that keeps the conversation history within a specified size limit. This example
@@ -158,17 +204,24 @@ uv run python examples/01_standalone_sdk/14_context_condenser.py
 
 ### Setting Up Condensing
 
-Configure a condenser when creating the agent:
+Create a `LLMSummarizingCondenser` to manage the context. 
+The condenser will automatically truncate conversation history when it exceeds max_size, and replaces the dropped events with an LLM-generated summary.
+
+This condenser triggers when there are more than `max_context_length` events in
+the conversation history, and always keeps the first `keep_first` events (system prompts,
+initial user messages) to preserve important context.
 
 ```python highlight={3-4}
-from openhands.sdk.context import LLMCondenser
+from openhands.sdk.context import LLMSummarizingCondenser
 
-condenser = LLMCondenser(llm=llm, max_context_length=100000)
+condenser = LLMSummarizingCondenser(
+    llm=llm.model_copy(update={"usage_id": "condenser"}), max_size=10, keep_first=2
+)
+
+# Agent with condenser
 agent = Agent(llm=llm, tools=tools, condenser=condenser)
 ```
 
-When context exceeds `max_context_length`, the condenser summarizes older messages to reduce token usage while maintaining important information.
-
 ## Next Steps
 
 - **[LLM Metrics](/sdk/guides/llm-metrics)** - Track token usage reduction

sdk/guides/llm-metrics.mdx

@@ -1,5 +1,5 @@
 ---
-title: LLM Metrics
+title: Metrics Tracking
 description: Track token usage, costs, and performance metrics for your agents.
 ---
 
@@ -99,31 +99,30 @@ uv run python examples/01_standalone_sdk/13_get_llm_metrics.py
 
 ### Getting Metrics
 
-Access metrics after running the conversation:
+Access metrics directly from the LLM object after running the conversation:
 
-```python highlight={3-6}
+```python highlight={3-4}
 conversation.run()
 
-metrics = conversation.get_llm_metrics()
-print(f"Input tokens: {metrics.input_tokens}")
-print(f"Output tokens: {metrics.output_tokens}")
-print(f"Total cost: ${metrics.cost:.4f}")
-```
-
-### Tracking Changes Over Time
-
-Compare metrics between operations:
-
-```python highlight={1,4}
-initial_metrics = conversation.get_llm_metrics()
-conversation.send_message("more work")
-conversation.run()
-final_metrics = conversation.get_llm_metrics()
-
-tokens_used = final_metrics.input_tokens - initial_metrics.input_tokens
+assert llm.metrics is not None
+print(f"Final LLM metrics: {llm.metrics.model_dump()}")
 ```
 
-Metrics include: `input_tokens`, `output_tokens`, `cost`, `api_calls`, and `cache_reads` (if supported).
+The `llm.metrics` object is an instance of the [Metrics class](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/utils/metrics.py), which provides detailed information including:
+
+- `accumulated_cost` - Total accumulated cost across all API calls
+- `accumulated_token_usage` - Aggregated token usage with fields like:
+  - `prompt_tokens` - Number of input tokens processed
+  - `completion_tokens` - Number of output tokens generated
+  - `cache_read_tokens` - Cache hits (if supported by the model)
+  - `cache_write_tokens` - Cache writes (if supported by the model)
+  - `reasoning_tokens` - Reasoning tokens (for models that support extended thinking)
+  - `context_window` - Context window size used
+- `costs` - List of individual cost records per API call
+- `token_usages` - List of detailed token usage records per API call
+- `response_latencies` - List of response latency metrics per API call
+
+For more details on the available metrics and methods, refer to the [source code](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/llm/utils/metrics.py).
 
 ## Next Steps