docs: sync code blocks and generate API reference (#317)

Synced from agent-sdk ref: main

Co-authored-by: xingyaoww <[email protected]>

Author: github-actions[bot]

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

@@ -6,13 +6,14 @@ description: API reference for openhands.sdk.agent module
 
 ### class Agent
 
-Bases: [`AgentBase`](#class-agentbase)
+Bases: `CriticMixin`, [`AgentBase`](#class-agentbase)
 
 Main agent implementation for OpenHands.
 
 The Agent class provides the core functionality for running AI agents that can
 interact with tools, process messages, and execute actions. It inherits from
-AgentBase and implements the agent execution logic.
+AgentBase and implements the agent execution logic. Critic-related functionality
+is provided by CriticMixin.
 
 #### Example
 

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

@@ -237,6 +237,7 @@ Bases: `OpenHandsModel`
 
 - `activated_knowledge_skills`: list[str]
 - `agent`: AgentBase
+- `agent_state`: dict[str, Any]
 - `blocked_actions`: dict[str, str]
 - `blocked_messages`: dict[str, str]
 - `confirmation_policy`: ConfirmationPolicyBase

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

@@ -305,6 +305,67 @@ Whether this model uses the OpenAI Responses API path.
 
 #### vision_is_active()
 
+### class LLMProfileStore
+
+Bases: `object`
+
+Standalone utility for persisting LLM configurations.
+
+#### Methods
+
+#### __init__()
+
+Initialize the profile store.
+
+* Parameters:
+  `base_dir` – Path to the directory where the profiles are stored.
+  If None is provided, the default directory is used, i.e.,
+  ~/.openhands/profiles.
+
+#### delete()
+
+Delete an existing profile.
+
+If the profile is not present in the profile directory, it does nothing.
+
+* Parameters:
+  `name` – Name of the profile to delete.
+* Raises:
+  `TimeoutError` – If the lock cannot be acquired.
+
+#### list()
+
+Returns a list of all profiles stored.
+
+* Returns:
+  List of profile filenames (e.g., [“default.json”, “gpt4.json”]).
+
+#### load()
+
+Load an LLM instance from the given profile name.
+
+* Parameters:
+  `name` – Name of the profile to load.
+* Returns:
+  An LLM instance constructed from the profile configuration.
+* Raises:
+  * `FileNotFoundError` – If the profile name does not exist.
+  * `ValueError` – If the profile file is corrupted or invalid.
+  * `TimeoutError` – If the lock cannot be acquired.
+
+#### save()
+
+Save a profile to the profile directory.
+
+Note that if a profile name already exists, it will be overwritten.
+
+* Parameters:
+  * `name` – Name of the profile to save.
+  * `llm` – LLM instance to save
+  * `include_secrets` – Whether to include the profile secrets. Defaults to False.
+* Raises:
+  `TimeoutError` – If the lock cannot be acquired.
+
 ### class LLMRegistry
 
 Bases: `object`

sdk/guides/critic.mdx

@@ -193,8 +193,8 @@ from openhands.tools.terminal import TerminalTool
 
 
 # Configuration
-# Higher threshold (70%) makes it more likely the agent needs multiple iterations
-# to demonstrate the how iterative refinement works.
+# Higher threshold (70%) makes it more likely the agent needs multiple iterations,
+# which better demonstrates how iterative refinement works.
 # Adjust as needed to see different behaviors.
 SUCCESS_THRESHOLD = float(os.getenv("CRITIC_SUCCESS_THRESHOLD", "0.7"))
 MAX_ITERATIONS = int(os.getenv("MAX_ITERATIONS", "3"))
@@ -330,6 +330,104 @@ The task is complete ONLY when:
 """
 
 
+llm_api_key = get_required_env("LLM_API_KEY")
+llm = LLM(
+    # Use a weaker model to increase likelihood of needing multiple iterations
+    model="anthropic/claude-haiku-4-5",
+    api_key=llm_api_key,
+    top_p=0.95,
+    base_url=os.getenv("LLM_BASE_URL", None),
+)
+
+# Setup critic with iterative refinement config
+# The IterativeRefinementConfig tells Conversation.run() to automatically
+# retry the task if the critic score is below the threshold
+iterative_config = IterativeRefinementConfig(
+    success_threshold=SUCCESS_THRESHOLD,
+    max_iterations=MAX_ITERATIONS,
+)
+
+# Auto-configure critic for All-Hands proxy or use explicit env vars
+critic = get_default_critic(llm)
+if critic is None:
+    print("⚠️  No All-Hands LLM proxy detected, trying explicit env vars...")
+    critic = APIBasedCritic(
+        server_url=get_required_env("CRITIC_SERVER_URL"),
+        api_key=get_required_env("CRITIC_API_KEY"),
+        model_name=get_required_env("CRITIC_MODEL_NAME"),
+        iterative_refinement=iterative_config,
+    )
+else:
+    # Add iterative refinement config to the auto-configured critic
+    critic = critic.model_copy(update={"iterative_refinement": iterative_config})
+
+# Create agent with critic (iterative refinement is built into the critic)
+agent = Agent(
+    llm=llm,
+    tools=[
+        Tool(name=TerminalTool.name),
+        Tool(name=FileEditorTool.name),
+        Tool(name=TaskTrackerTool.name),
+    ],
+    critic=critic,
+)
+
+# Create workspace
+workspace = Path(tempfile.mkdtemp(prefix="critic_demo_"))
+print(f"📁 Created workspace: {workspace}")
+
+# Create conversation - iterative refinement is handled automatically
+# by Conversation.run() based on the critic's config
+conversation = Conversation(
+    agent=agent,
+    workspace=str(workspace),
+)
+
+print("\n" + "=" * 70)
+print("🚀 Starting Iterative Refinement with Critic Model")
+print("=" * 70)
+print(f"Success threshold: {SUCCESS_THRESHOLD:.0%}")
+print(f"Max iterations: {MAX_ITERATIONS}")
+
+# Send the task and run - Conversation.run() handles retries automatically
+conversation.send_message(INITIAL_TASK_PROMPT)
+conversation.run()
+
+# Print additional info about created files
+print("\nCreated files:")
+for path in sorted(workspace.rglob("*")):
+    if path.is_file():
+        relative = path.relative_to(workspace)
+        print(f"  - {relative}")
+
+# Report cost
+cost = llm.metrics.accumulated_cost
+print(f"\nEXAMPLE_COST: {cost:.4f}")
+```
+Hello world!
+This is a well-known test file.
+
+It has 5 lines, including empty ones.
+Numbers like 42 and 3.14 don't count as words.
+```
+
+2. Run: `python wordstats/cli.py sample.txt`
+   Expected output:
+   - Lines: 5
+   - Words: 21
+   - Chars: 130
+   - Unique words: 21
+
+3. Run the tests: `python -m pytest wordstats/tests/ -v`
+   ALL tests must pass.
+
+The task is complete ONLY when:
+- All files exist
+- The CLI outputs the correct stats for sample.txt
+- All 5+ tests pass
+"""
+
+
 llm_api_key = get_required_env("LLM_API_KEY")
 llm = LLM(
     # Use a weaker model to increase likelihood of needing multiple iterations

sdk/guides/llm-profile-store.mdx

@@ -113,7 +113,7 @@ from openhands.sdk import LLM, LLMProfileStore
 store = LLMProfileStore(base_dir=tempfile.mkdtemp())
 
 
-# 1. Create to LLM profiles with different usage
+# 1. Create two LLM profiles with different usage
 
 api_key = os.getenv("LLM_API_KEY")
 assert api_key is not None, "LLM_API_KEY environment variable is not set."
@@ -152,6 +152,7 @@ print(f"Stored profiles: {store.list()}")
 # 4. Load a profile
 
 loaded = store.load("fast")
+assert isinstance(loaded, LLM)
 print(
     "Loaded profile. "
     f"usage:{loaded.usage_id}, "
@@ -163,6 +164,8 @@ print(
 
 store.delete("creative")
 print(f"After deletion: {store.list()}")
+
+print("EXAMPLE_COST: 0")
 ```
 
 <RunExampleCode path_to_script="examples/01_standalone_sdk/37_llm_profile_store.py"/>