Merge branch 'main' into feat/tools-j2-descriptions

Author: nikhilk7153

.github/run-eval/resolve_model_config.py

@@ -52,6 +52,14 @@
             "litellm_extra_body": {"enable_thinking": True},
         },
     },
+    "qwen3.5-flash": {
+        "id": "qwen3.5-flash",
+        "display_name": "Qwen3.5 Flash",
+        "llm_config": {
+            "model": "litellm_proxy/dashscope/qwen3.5-flash-2026-02-23",
+            "temperature": 0.0,
+        },
+    },
     "claude-4.5-opus": {
         "id": "claude-4.5-opus",
         "display_name": "Claude 4.5 Opus",

AGENTS.md

@@ -120,6 +120,16 @@ When reviewing code, provide constructive feedback:
 
 When adding non-Python files (JS, templates, etc.) loaded at runtime, add them to `openhands-agent-server/openhands/agent_server/agent-server.spec` using `collect_data_files`.
 
+# Bedrock + LiteLLM note
+
+- LiteLLM interprets the `api_key` parameter for Bedrock models as an **AWS bearer token**.
+  When using IAM/SigV4 auth (AWS credentials / profiles), do **not** forward `LLM.api_key`
+  to LiteLLM for Bedrock models, or Bedrock may return:
+  `Invalid API Key format: Must start with pre-defined prefix`.
+- If you need Bedrock bearer-token auth, set `AWS_BEARER_TOKEN_BEDROCK` in the environment
+  (instead of using `LLM_API_KEY`).
+
+
 </DEV_SETUP>
 
 <PR_ARTIFACTS>

examples/01_standalone_sdk/25_agent_delegation.py

@@ -20,11 +20,11 @@
     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
 

examples/01_standalone_sdk/41_task_tool_set.py

@@ -0,0 +1,112 @@
+"""
+Animal Quiz with Task Tool Set
+
+Demonstrates the TaskToolSet with a main agent delegating to an
+animal-expert sub-agent. The flow is:
+
+1. User names an animal.
+2. Main agent delegates to the "animal_expert" sub-agent to generate
+   a multiple-choice question about that animal.
+3. Main agent shows the question to the user.
+4. User picks an answer.
+5. Main agent delegates again to the same sub-agent type to check
+   whether the answer is correct and explain why.
+"""
+
+import os
+
+from openhands.sdk import LLM, Agent, AgentContext, Conversation, Tool
+from openhands.sdk.context import Skill
+from openhands.sdk.subagent import register_agent
+from openhands.tools.delegate import DelegationVisualizer
+from openhands.tools.task import TaskToolSet
+
+
+llm = LLM(
+    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
+    api_key=os.getenv("LLM_API_KEY"),
+    base_url=os.getenv("LLM_BASE_URL", None),
+)
+# ── Register the animal expert sub-agent ─────────────────────────────
+
+
+def create_animal_expert(llm: LLM) -> Agent:
+    """Factory for the animal-expert sub-agent."""
+    return Agent(
+        llm=llm,
+        tools=[],  # no tools needed – pure knowledge
+        agent_context=AgentContext(
+            skills=[
+                Skill(
+                    name="animal_expertise",
+                    content=(
+                        "You are a world-class zoologist. "
+                        "When asked to generate a quiz question, respond with "
+                        "EXACTLY this format and nothing else:\n\n"
+                        "Question: <question text>\n"
+                        "A) <option>\n"
+                        "B) <option>\n"
+                        "C) <option>\n"
+                        "D) <option>\n\n"
+                        "When asked to verify an answer, state whether it is "
+                        "correct or incorrect, reveal the right answer, and "
+                        "give a short fun-fact explanation."
+                    ),
+                    trigger=None,  # always active
+                )
+            ],
+            system_message_suffix="Keep every response concise.",
+        ),
+    )
+
+
+register_agent(
+    name="animal_expert",
+    factory_func=create_animal_expert,
+    description="Zoologist that creates and verifies animal quiz questions.",
+)
+
+# ── Main agent ───────────────────────────────────────────────────────
+
+main_agent = Agent(
+    llm=llm,
+    tools=[Tool(name=TaskToolSet.name)],
+)
+
+conversation = Conversation(
+    agent=main_agent,
+    workspace=os.getcwd(),
+    visualizer=DelegationVisualizer(name="QuizHost"),
+)
+
+# ── Round 1: generate the question ──────────────────────────────────
+
+animal = input("Pick an animal: ")
+
+conversation.send_message(
+    f"The user chose the animal: {animal}. "
+    "Use the task tool to delegate to the 'animal_expert' sub-agent "
+    "and ask it to generate a single multiple-choice question (A-D) "
+    f"about {animal}. "
+    "Once you get the question back, display it to the user exactly "
+    "as the sub-agent returned it and ask the user to pick A, B, C, or D."
+)
+conversation.run()
+
+# ── Round 2: verify the answer ──────────────────────────────────────
+
+answer = input("Your answer (A/B/C/D): ")
+
+conversation.send_message(
+    f"The user answered: {answer}. "
+    "Use the task tool to delegate to the 'animal_expert' sub-agent again "
+    f"and ask it whether '{answer}' is the correct answer to the question "
+    "it generated earlier. Don't include the question; instead, use the "
+    "'resume' parameter to continue the previous conversation."
+)
+conversation.run()
+
+# ── Done ────────────────────────────────────────────────────────────
+
+cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+print(f"\nEXAMPLE_COST: {cost}")

examples/01_standalone_sdk/42_file_based_subagents.py

@@ -0,0 +1,69 @@
+"""Example: Defining a sub-agent inline with AgentDefinition.
+
+Defines a grammar-checker sub-agent using AgentDefinition, registers it,
+and delegates work to it from an orchestrator agent. The orchestrator then
+asks the builtin default agent to judge the results.
+"""
+
+import os
+from pathlib import Path
+
+from openhands.sdk import (
+    LLM,
+    Agent,
+    Conversation,
+    Tool,
+    agent_definition_to_factory,
+    register_agent,
+)
+from openhands.sdk.subagent import AgentDefinition
+from openhands.sdk.tool import register_tool
+from openhands.tools.delegate import DelegateTool, DelegationVisualizer
+
+
+# 1. Define a sub-agent using AgentDefinition
+grammar_checker = AgentDefinition(
+    name="grammar-checker",
+    description="Checks documents for grammatical errors.",
+    tools=["file_editor"],
+    system_prompt="You are a grammar expert. Find and list grammatical errors.",
+)
+
+# 2. Register it in the delegate registry
+register_agent(
+    name=grammar_checker.name,
+    factory_func=agent_definition_to_factory(grammar_checker),
+    description=grammar_checker.description,
+)
+
+# 3. Set up the orchestrator agent with the DelegateTool
+llm = LLM(
+    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
+    api_key=os.getenv("LLM_API_KEY"),
+    base_url=os.getenv("LLM_BASE_URL"),
+    usage_id="file-agents-demo",
+)
+
+register_tool("DelegateTool", DelegateTool)
+main_agent = Agent(
+    llm=llm,
+    tools=[Tool(name="DelegateTool")],
+)
+conversation = Conversation(
+    agent=main_agent,
+    workspace=Path.cwd(),
+    visualizer=DelegationVisualizer(name="Orchestrator"),
+)
+
+# 4. Ask the orchestrator to delegate to our agent
+task = (
+    "Please delegate to the grammar-checker agent and ask it to review "
+    "the README.md file in search of grammatical errors.\n"
+    "Then ask the default agent to judge the errors."
+)
+conversation.send_message(task)
+conversation.run()
+
+cost = conversation.conversation_stats.get_combined_metrics().accumulated_cost
+print(f"\nTotal cost: ${cost:.4f}")
+print(f"EXAMPLE_COST: {cost:.4f}")

openhands-agent-server/openhands/agent_server/api.py

@@ -24,6 +24,7 @@
 from openhands.agent_server.file_router import file_router
 from openhands.agent_server.git_router import git_router
 from openhands.agent_server.hooks_router import hooks_router
+from openhands.agent_server.llm_router import llm_router
 from openhands.agent_server.middleware import LocalhostCORSMiddleware
 from openhands.agent_server.server_details_router import (
     get_server_info,
@@ -196,6 +197,7 @@ def _add_api_routes(app: FastAPI, config: Config) -> None:
     api_router.include_router(desktop_router)
     api_router.include_router(skills_router)
     api_router.include_router(hooks_router)
+    api_router.include_router(llm_router)
     app.include_router(api_router)
     app.include_router(sockets_router)
 
@@ -342,6 +344,8 @@ def create_app(config: Config | None = None) -> FastAPI:
     if config is None:
         config = get_default_config()
     app = _create_fastapi_instance()
+    app.state.config = config
+
     _add_api_routes(app, config)
     _setup_static_files(app, config)
     app.add_middleware(LocalhostCORSMiddleware, allow_origins=config.allow_cors_origins)

openhands-agent-server/openhands/agent_server/dependencies.py

@@ -1,6 +1,6 @@
 from uuid import UUID
 
-from fastapi import Depends, HTTPException, Query, Request, status
+from fastapi import Depends, HTTPException, Request, status
 from fastapi.security import APIKeyHeader
 
 from openhands.agent_server.config import Config
@@ -26,23 +26,6 @@ def check_session_api_key(
     return check_session_api_key
 
 
-def create_websocket_session_api_key_dependency(config: Config):
-    """Create a WebSocket session API key dependency with the given config.
-
-    WebSocket connections cannot send custom headers directly from browsers,
-    so we use query parameters instead.
-    """
-
-    def check_websocket_session_api_key(
-        session_api_key: str | None = Query(None, alias="session_api_key"),
-    ):
-        """Check the session API key from query parameter for WebSocket connections."""
-        if config.session_api_keys and session_api_key not in config.session_api_keys:
-            raise HTTPException(status.HTTP_401_UNAUTHORIZED)
-
-    return check_websocket_session_api_key
-
-
 def get_conversation_service(request: Request):
     """Get the conversation service from app state.
 

openhands-agent-server/openhands/agent_server/docker/Dockerfile

@@ -30,7 +30,7 @@ COPY --chown=${USERNAME}:${USERNAME} openhands-tools ./openhands-tools
 COPY --chown=${USERNAME}:${USERNAME} openhands-workspace ./openhands-workspace
 COPY --chown=${USERNAME}:${USERNAME} openhands-agent-server ./openhands-agent-server
 RUN --mount=type=cache,target=/home/${USERNAME}/.cache,uid=${UID},gid=${GID} \
-    uv python install 3.12 && uv venv --python 3.12 .venv && uv sync --frozen --no-editable --managed-python
+    uv python install 3.12 && uv venv --python 3.12 .venv && uv sync --frozen --no-editable --managed-python --extra boto3
 
 ####################################################################################
 # Binary Builder (binary mode)
@@ -41,7 +41,7 @@ ARG USERNAME UID GID
 
 # We need --dev for pyinstaller
 RUN --mount=type=cache,target=/home/${USERNAME}/.cache,uid=${UID},gid=${GID} \
-    uv sync --frozen --dev --no-editable
+    uv sync --frozen --dev --no-editable --extra boto3
 
 RUN --mount=type=cache,target=/home/${USERNAME}/.cache,uid=${UID},gid=${GID} \
     uv run pyinstaller openhands-agent-server/openhands/agent_server/agent-server.spec

openhands-agent-server/openhands/agent_server/llm_router.py

@@ -0,0 +1,78 @@
+"""Router for LLM model and provider information endpoints."""
+
+from fastapi import APIRouter, Query
+from pydantic import BaseModel
+
+from openhands.sdk.llm.utils.unverified_models import (
+    _extract_model_and_provider,
+    _get_litellm_provider_names,
+    get_supported_llm_models,
+)
+from openhands.sdk.llm.utils.verified_models import VERIFIED_MODELS
+
+
+llm_router = APIRouter(prefix="/llm", tags=["LLM"])
+
+
+class ProvidersResponse(BaseModel):
+    """Response containing the list of available LLM providers."""
+
+    providers: list[str]
+
+
+class ModelsResponse(BaseModel):
+    """Response containing the list of available LLM models."""
+
+    models: list[str]
+
+
+class VerifiedModelsResponse(BaseModel):
+    """Response containing verified models organized by provider."""
+
+    models: dict[str, list[str]]
+
+
+@llm_router.get("/providers", response_model=ProvidersResponse)
+async def list_providers() -> ProvidersResponse:
+    """List all available LLM providers supported by LiteLLM."""
+    providers = sorted(_get_litellm_provider_names())
+    return ProvidersResponse(providers=providers)
+
+
+@llm_router.get("/models", response_model=ModelsResponse)
+async def list_models(
+    provider: str | None = Query(
+        default=None,
+        description="Filter models by provider (e.g., 'openai', 'anthropic')",
+    ),
+) -> ModelsResponse:
+    """List all available LLM models supported by LiteLLM.
+
+    Args:
+        provider: Optional provider name to filter models by.
+
+    Note: Bedrock models are excluded unless AWS credentials are configured.
+    """
+    all_models = get_supported_llm_models()
+
+    if provider is None:
+        models = sorted(set(all_models))
+    else:
+        filtered_models = []
+        for model in all_models:
+            model_provider, model_id, separator = _extract_model_and_provider(model)
+            if model_provider == provider:
+                filtered_models.append(model)
+        models = sorted(set(filtered_models))
+
+    return ModelsResponse(models=models)
+
+
+@llm_router.get("/models/verified", response_model=VerifiedModelsResponse)
+async def list_verified_models() -> VerifiedModelsResponse:
+    """List all verified LLM models organized by provider.
+
+    Verified models are those that have been tested and confirmed to work well
+    with OpenHands.
+    """
+    return VerifiedModelsResponse(models=VERIFIED_MODELS)