Sync code blocks with latest agent-sdk examples

Updates code examples in documentation files to match current
source files in the agent-sdk repository.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

sdk/guides/agent-acp.mdx

@@ -106,7 +106,9 @@ This example is available on GitHub: [examples/01_standalone_sdk/40_acp_agent_ex
 """Example: Using ACPAgent with Claude Code ACP server.
 
 This example shows how to use an ACP-compatible server (claude-code-acp)
-as the agent backend instead of direct LLM calls.
+as the agent backend instead of direct LLM calls.  It also demonstrates
+``ask_agent()`` — a stateless side-question that forks the ACP session
+and leaves the main conversation untouched.
 
 Prerequisites:
     - Node.js / npx available
@@ -122,17 +124,25 @@ from openhands.sdk.agent import ACPAgent
 from openhands.sdk.conversation import Conversation
 
 
-agent = ACPAgent(acp_command=["npx", "-y", "claude-code-acp"])
+agent = ACPAgent(acp_command=["npx", "-y", "@zed-industries/claude-code-acp"])
 
 try:
     cwd = os.getcwd()
     conversation = Conversation(agent=agent, workspace=cwd)
 
+    # --- Main conversation turn ---
     conversation.send_message(
         "List the Python source files under openhands-sdk/openhands/sdk/agent/, "
         "then read the __init__.py and summarize what agent classes are exported."
     )
     conversation.run()
+
+    # --- ask_agent: stateless side-question via fork_session ---
+    print("\n--- ask_agent ---")
+    response = conversation.ask_agent(
+        "Based on what you just saw, which agent class is the newest addition?"
+    )
+    print(f"ask_agent response: {response}")
 finally:
     # Clean up the ACP server subprocess
     agent.close()

sdk/guides/agent-delegation.mdx

@@ -168,8 +168,6 @@ which then merges both analyses into a single consolidated report.
 
 import os
 
-from pydantic import SecretStr
-
 from openhands.sdk import (
     LLM,
     Agent,
@@ -179,36 +177,32 @@ from openhands.sdk import (
     get_logger,
 )
 from openhands.sdk.context import Skill
+from openhands.sdk.subagent import register_agent
 from openhands.sdk.tool import register_tool
 from openhands.tools.delegate import (
     DelegateTool,
     DelegationVisualizer,
-    register_agent,
 )
-from openhands.tools.preset.default import get_default_tools
+from openhands.tools.preset.default import get_default_tools, register_builtins_agents
 
 
 ONLY_RUN_SIMPLE_DELEGATION = False
 
 logger = get_logger(__name__)
 
 # Configure LLM and agent
-# You can get an API key from https://app.all-hands.dev/settings/api-keys
-api_key = os.getenv("LLM_API_KEY")
-assert api_key is not None, "LLM_API_KEY environment variable is not set."
-model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
 llm = LLM(
-    model=model,
-    api_key=SecretStr(api_key),
+    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
+    api_key=os.getenv("LLM_API_KEY"),
     base_url=os.environ.get("LLM_BASE_URL", None),
     usage_id="agent",
 )
 
 cwd = os.getcwd()
 
-register_tool("DelegateTool", DelegateTool)
-tools = get_default_tools(enable_browser=False)
-tools.append(Tool(name="DelegateTool"))
+tools = get_default_tools(enable_browser=True)
+tools.append(Tool(name=DelegateTool.name))
+register_builtins_agents()
 
 main_agent = Agent(
     llm=llm,
@@ -220,7 +214,7 @@ conversation = Conversation(
     visualizer=DelegationVisualizer(name="Delegator"),
 )
 
-task_message = (
+conversation.send_message(
     "Forget about coding. Let's switch to travel planning. "
     "Let's plan a trip to London. I have two issues I need to solve: "
     "Lodging: what are the best areas to stay at while keeping budget in mind? "
@@ -231,7 +225,6 @@ task_message = (
     "They should keep it short. After getting the results, merge both analyses "
     "into a single consolidated report.\n\n"
 )
-conversation.send_message(task_message)
 conversation.run()
 
 conversation.send_message(
@@ -240,18 +233,57 @@ conversation.send_message(
 conversation.run()
 
 # Report cost for simple delegation example
-cost_1 = conversation.conversation_stats.get_combined_metrics().accumulated_cost
-print(f"EXAMPLE_COST (simple delegation): {cost_1}")
+cost_simple = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+print(f"EXAMPLE_COST (simple delegation): {cost_simple}")
 
 print("Simple delegation example done!", "\n" * 20)
 
-
-# -------- Agent Delegation Second Part: User-Defined Agent Types --------
-
 if ONLY_RUN_SIMPLE_DELEGATION:
+    # For CI: always emit the EXAMPLE_COST marker before exiting.
+    print(f"EXAMPLE_COST: {cost_simple}")
     exit(0)
 
 
+# -------- Agent Delegation Second Part: Built-in Agent Types (Explore + Bash) --------
+
+main_agent = Agent(
+    llm=llm,
+    tools=[Tool(name=DelegateTool.name)],
+)
+conversation = Conversation(
+    agent=main_agent,
+    workspace=cwd,
+    visualizer=DelegationVisualizer(name="Delegator (builtins)"),
+)
+
+builtin_task_message = (
+    "Demonstrate SDK built-in sub-agent types. "
+    "1) Spawn an 'explore' sub-agent and ask it to list the markdown files in "
+    "openhands-sdk/openhands/sdk/subagent/builtins/ and summarize what each "
+    "built-in agent type is for (based on the file contents). "
+    "2) Spawn a 'bash' sub-agent and ask it to run `python --version` in the "
+    "terminal and return the exact output. "
+    "3) Merge both results into a short report. "
+    "Do not use internet access."
+)
+
+print("=" * 100)
+print("Demonstrating built-in agent delegation (explore + bash)...")
+print("=" * 100)
+
+conversation.send_message(builtin_task_message)
+conversation.run()
+
+# Report cost for builtin agent types example
+cost_builtin = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+print(f"EXAMPLE_COST (builtin agents): {cost_builtin}")
+
+print("Built-in agent delegation example done!", "\n" * 20)
+
+
+# -------- Agent Delegation Third Part: User-Defined Agent Types --------
+
+
 def create_lodging_planner(llm: LLM) -> Agent:
     """Create a lodging planner focused on London stays."""
     skills = [
@@ -349,13 +381,15 @@ conversation.send_message(
 conversation.run()
 
 # Report cost for user-defined agent types example
-cost_2 = conversation.conversation_stats.get_combined_metrics().accumulated_cost
-print(f"EXAMPLE_COST (user-defined agents): {cost_2}")
+cost_user_defined = (
+    conversation.conversation_stats.get_combined_metrics().accumulated_cost
+)
+print(f"EXAMPLE_COST (user-defined agents): {cost_user_defined}")
 
 print("All done!")
 
 # Full example cost report for CI workflow
-print(f"EXAMPLE_COST: {cost_1 + cost_2}")
+print(f"EXAMPLE_COST: {cost_simple + cost_builtin + cost_user_defined}")
 ```
 
 <RunExampleCode path_to_script="examples/01_standalone_sdk/25_agent_delegation.py"/>

sdk/guides/agent-server/local-server.mdx

@@ -111,6 +111,7 @@ This example shows how to programmatically start a local agent server and intera
 import os
 import subprocess
 import sys
+import tempfile
 import threading
 import time
 
@@ -268,7 +269,9 @@ with ManagedAPIServer(port=8001) as server:
 
     # Create RemoteConversation with callbacks
     # NOTE: Workspace is required for RemoteConversation
-    workspace = Workspace(host=server.base_url)
+    # Use a temp directory that exists and is accessible in CI environments
+    temp_workspace_dir = tempfile.mkdtemp(prefix="agent_server_demo_")
+    workspace = Workspace(host=server.base_url, working_dir=temp_workspace_dir)
     result = workspace.execute_command("pwd")
     logger.info(
         f"Command '{result.command}' completed with exit code {result.exit_code}"

sdk/guides/browser-session-recording.mdx

@@ -46,7 +46,7 @@ browsing session.
 The recording will be automatically saved to the persistence directory when
 browser_stop_recording is called. You can replay it with:
     - rrweb-player: https://github.com/rrweb-io/rrweb/tree/master/packages/rrweb-player
-    - Online viewer: https://www.rrweb.io/
+    - Online viewer: https://www.rrweb.io/demo/
 """
 
 import json

sdk/guides/github-workflows/pr-review.mdx

@@ -162,7 +162,8 @@ jobs:
             - name: Run PR Review
               uses: ./.github/actions/pr-review
               with:
-                  # LLM configuration
+                  # LLM model(s) to use. Can be comma-separated for A/B testing
+                  # - one model will be randomly selected per review
                   llm-model: anthropic/claude-sonnet-4-5-20250929
                   llm-base-url: ''
                   # Review style: roasted (other option: standard)