docs: sync documentation from agent-sdk

- Synced code blocks from examples

- Generated API reference documentation

Synced from agent-sdk ref: main

Author: github-actions[bot]

docs.json

@@ -140,7 +140,9 @@
           },
           {
             "group": "Tips and Tricks",
-            "pages": ["openhands/usage/tips/prompting-best-practices"]
+            "pages": [
+              "openhands/usage/tips/prompting-best-practices"
+            ]
           },
           {
             "group": "Troubleshooting & Feedback",
@@ -280,7 +282,9 @@
       },
       {
         "tab": "Success Stories",
-        "pages": ["success-stories/index"]
+        "pages": [
+          "success-stories/index"
+        ]
       }
     ],
     "global": {
@@ -321,7 +325,7 @@
     }
   },
   "banner": {
-    "content": "📢 **GitHub Org Rename:** All-Hands-AI to OpenHands on Monday Oct 20th at 18:00 UTC. [Migration details →](https://github.com/OpenHands/OpenHands/issues/11376)",
+    "content": "\ud83d\udce2 **GitHub Org Rename:** All-Hands-AI to OpenHands on Monday Oct 20th at 18:00 UTC. [Migration details \u2192](https://github.com/OpenHands/OpenHands/issues/11376)",
     "dismissible": true
   },
   "head": [
@@ -333,7 +337,12 @@
     }
   ],
   "contextual": {
-    "options": ["copy", "view", "chatgpt", "claude"]
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude"
+    ]
   },
   "redirects": [
     {

sdk/api-reference/openhands.sdk.conversation.mdx

@@ -29,6 +29,10 @@ exchange, execution control, and state management.
 
 #### Methods
 
+#### __init__()
+
+Initialize the base conversation with span tracking.
+
 #### abstractmethod close()
 
 #### static compose_callbacks()

sdk/api-reference/openhands.sdk.llm.mdx

@@ -51,11 +51,11 @@ retry logic, and tool calling capabilities.
 #### Properties
 
 - `OVERRIDE_ON_SERIALIZE`: tuple[str, ...]
-- `api_key`: SecretStr | None
+- `api_key`: str | SecretStr | None
 - `api_version`: str | None
-- `aws_access_key_id`: SecretStr | None
+- `aws_access_key_id`: str | SecretStr | None
 - `aws_region_name`: str | None
-- `aws_secret_access_key`: SecretStr | None
+- `aws_secret_access_key`: str | SecretStr | None
 - `base_url`: str | None
 - `caching_prompt`: bool
 - `custom_llm_provider`: str | None
@@ -90,6 +90,7 @@ retry logic, and tool calling capabilities.
 - `openrouter_site_url`: str
 - `output_cost_per_token`: float | None
 - `reasoning_effort`: Literal['low', 'medium', 'high', 'none'] | None
+- `reasoning_summary`: Literal['auto', 'concise', 'detailed'] | None
 - `retry_listener`: SkipJsonSchema[Callable[[int, int], None] | None]
 - `retry_max_wait`: int
 - `retry_min_wait`: int

sdk/api-reference/openhands.sdk.tool.mdx

@@ -76,15 +76,37 @@ Base schema for output observation.
 
 #### Properties
 
+- `ERROR_MESSAGE_HEADER`: ClassVar[str] = '[An error occurred during execution.]n'
+- `content`: list[TextContent | ImageContent]
+- `is_error`: bool
 - `kind`: str
 - `model_config`: ClassVar[ConfigDict] = (configuration object)
   Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
+- `text`: str
+  Extract all text content from the observation.
+  * Returns:
+    Concatenated text from all TextContent items in content.
 - `to_llm_content`: Sequence[TextContent | ImageContent]
-  Get the observation string to show to the agent.
+  Default content formatting for converting observation to LLM readable content.
+  Subclasses can override to provide richer content (e.g., images, diffs).
 - `visualize`: Text
-  Return Rich Text representation of this action.
-  This method can be overridden by subclasses to customize visualization.
-  The base implementation displays all action fields systematically.
+  Return Rich Text representation of this observation.
+  Subclasses can override for custom visualization; by default we show the
+  same text that would be sent to the LLM.
+
+#### Methods
+
+#### classmethod from_text()
+
+Utility to create an Observation from a simple text string.
+
+* Parameters:
+  * `text` – The text content to include in the observation.
+  * `is_error` – Whether this observation represents an error.
+   kwargs* – Additional fields for the observation subclass.
+* Returns:
+  An Observation instance with the text wrapped in a TextContent.
+
 ### class ThinkTool
 
 Bases: `ToolDefinition[ThinkAction, ThinkObservation]`

sdk/getting-started.mdx

@@ -74,37 +74,32 @@ Here's a complete example that creates an agent and asks it to perform a simple
 ```python icon="python" expandable examples/01_standalone_sdk/01_hello_world.py
 import os
 
-from pydantic import SecretStr
+from openhands.sdk import LLM, Agent, Conversation, Tool
+from openhands.tools.execute_bash import BashTool
+from openhands.tools.file_editor import FileEditorTool
+from openhands.tools.task_tracker import TaskTrackerTool
 
-from openhands.sdk import LLM, Conversation
-from openhands.tools.preset.default import get_default_agent
 
-
-# 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", "openhands/claude-sonnet-4-5-20250929")
-base_url = os.getenv("LLM_BASE_URL")
 llm = LLM(
-    model=model,
-    api_key=SecretStr(api_key),
-    base_url=base_url,
-    usage_id="agent",
+    model="anthropic/claude-sonnet-4-5-20250929",
+    api_key=os.getenv("LLM_API_KEY"),
+)
+
+agent = Agent(
+    llm=llm,
+    tools=[
+        Tool(name=BashTool.name),
+        Tool(name=FileEditorTool.name),
+        Tool(name=TaskTrackerTool.name),
+    ],
 )
-agent = get_default_agent(llm=llm, cli_mode=True)
 
-# Start a conversation and send some messages
 cwd = os.getcwd()
 conversation = Conversation(agent=agent, workspace=cwd)
 
-# Send a message and let the agent run
 conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
 conversation.run()
-
-# Report cost
-cost = llm.metrics.accumulated_cost
-print(f"EXAMPLE_COST: {cost}")
+print("All done!")
 ```
 
 Run the example:

sdk/guides/agent-server/docker-sandbox.mdx

@@ -60,9 +60,9 @@ def detect_platform():
 #    the Docker container automatically
 with DockerWorkspace(
     # dynamically build agent-server image
-    # base_image="nikolaik/python-nodejs:python3.12-nodejs22",
+    base_image="nikolaik/python-nodejs:python3.12-nodejs22",
     # use pre-built image for faster startup
-    server_image="ghcr.io/openhands/agent-server:main-python",
+    # server_image="ghcr.io/openhands/agent-server:main-python",
     host_port=8010,
     platform=detect_platform(),
 ) as workspace:
@@ -122,6 +122,9 @@ with DockerWorkspace(
         logger.info("✅ Second task completed!")
 
         # Report cost (must be before conversation.close())
+        conversation.state._cached_state = (
+            None  # Invalidate cache to fetch latest stats
+        )
         cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
         print(f"EXAMPLE_COST: {cost}")
     finally:
@@ -467,7 +470,7 @@ def detect_platform():
 # Create a Docker-based remote workspace with extra ports for browser access
 with DockerWorkspace(
     base_image="nikolaik/python-nodejs:python3.12-nodejs22",
-    host_port=8010,
+    host_port=8011,
     platform=detect_platform(),
     extra_ports=True,  # Expose extra ports for VSCode and VNC
 ) as workspace:
@@ -506,17 +509,26 @@ with DockerWorkspace(
     )
     conversation.run()
 
-    # Wait for user confirm to exit
-    y = None
-    while y != "y":
-        y = input(
-            "Because you've enabled extra_ports=True in DockerWorkspace, "
-            "you can open a browser tab to see the *actual* browser OpenHands "
-            "is interacting with via VNC.\n\n"
-            "Link: http://localhost:8012/vnc.html?autoconnect=1&resize=remote\n\n"
-            "Press 'y' and Enter to exit and terminate the workspace.\n"
-            ">> "
+    conversation.state._cached_state = None  # Invalidate cache to fetch latest stats
+    cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+    print(f"EXAMPLE_COST: {cost}")
+
+    if os.getenv("CI"):
+        logger.info(
+            "CI environment detected; skipping interactive prompt and closing workspace."  # noqa: E501
         )
+    else:
+        # Wait for user confirm to exit when running locally
+        y = None
+        while y != "y":
+            y = input(
+                "Because you've enabled extra_ports=True in DockerWorkspace, "
+                "you can open a browser tab to see the *actual* browser OpenHands "
+                "is interacting with via VNC.\n\n"
+                "Link: http://localhost:8012/vnc.html?autoconnect=1&resize=remote\n\n"
+                "Press 'y' and Enter to exit and terminate the workspace.\n"
+                ">> "
+            )
 ```
 
 ```bash Running the Example

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

@@ -254,6 +254,9 @@ with ManagedAPIServer(port=8001) as server:
                 logger.info(f"  - {event}")
 
         # Report cost (must be before conversation.close())
+        conversation.state._cached_state = (
+            None  # Invalidate cache to fetch latest stats
+        )
         cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
         print(f"EXAMPLE_COST: {cost}")
 

sdk/guides/custom-tools.mdx

@@ -134,8 +134,10 @@ class GrepExecutor(ToolExecutor[GrepAction, GrepObservation]):
         files: set[str] = set()
 
         # grep returns exit code 1 when no matches; treat as empty
-        if result.output.strip():
-            for line in result.output.strip().splitlines():
+        output_text = result.text
+
+        if output_text.strip():
+            for line in output_text.strip().splitlines():
                 matches.append(line)
                 # Expect "path:line:content" — take the file part before first ":"
                 file_path = line.split(":", 1)[0]

sdk/guides/hello-world.mdx

@@ -12,37 +12,32 @@ This is the most basic example showing how to set up and run an OpenHands agent:
 ```python icon="python" examples/01_standalone_sdk/01_hello_world.py
 import os
 
-from pydantic import SecretStr
+from openhands.sdk import LLM, Agent, Conversation, Tool
+from openhands.tools.execute_bash import BashTool
+from openhands.tools.file_editor import FileEditorTool
+from openhands.tools.task_tracker import TaskTrackerTool
 
-from openhands.sdk import LLM, Conversation
-from openhands.tools.preset.default import get_default_agent
 
-
-# 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", "openhands/claude-sonnet-4-5-20250929")
-base_url = os.getenv("LLM_BASE_URL")
 llm = LLM(
-    model=model,
-    api_key=SecretStr(api_key),
-    base_url=base_url,
-    usage_id="agent",
+    model="anthropic/claude-sonnet-4-5-20250929",
+    api_key=os.getenv("LLM_API_KEY"),
+)
+
+agent = Agent(
+    llm=llm,
+    tools=[
+        Tool(name=BashTool.name),
+        Tool(name=FileEditorTool.name),
+        Tool(name=TaskTrackerTool.name),
+    ],
 )
-agent = get_default_agent(llm=llm, cli_mode=True)
 
-# Start a conversation and send some messages
 cwd = os.getcwd()
 conversation = Conversation(agent=agent, workspace=cwd)
 
-# Send a message and let the agent run
 conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
 conversation.run()
-
-# Report cost
-cost = llm.metrics.accumulated_cost
-print(f"EXAMPLE_COST: {cost}")
+print("All done!")
 ```
 
 ```bash Running the Example