+--------------+ +-----------------+ +---------------+ | Agent |<-----| Conversation |----->| Workspace | | (stateless, | | (loop runner, | | (Local/Docker | | Pydantic) | | state, EventLog)| | /Remote) | +------^-------+ +--------^--------+ +-------^-------+ | | | | uses | persists / streams | executes v v v +-------+ +----------+ +---------------+ | LLM | | EventLog | | bash, python | |+Cond. | +----------+ | jupyter, | +-------+ | browser, FS | +---------------+ +--------------+ +-----------------+ +---------------+ | Agent |<-----| Conversation |----->| Workspace | | (stateless, | | (loop runner, | | (Local/Docker | | Pydantic) | | state, EventLog)| | /Remote) | +------^-------+ +--------^--------+ +-------^-------+ | | | | uses | persists / streams | executes v v v +-------+ +----------+ +---------------+ | LLM | | EventLog | | bash, python | |+Cond. | +----------+ | jupyter, | +-------+ | browser, FS | +---------------+ +--------------+ +-----------------+ +---------------+ | Agent |<-----| Conversation |----->| Workspace | | (stateless, | | (loop runner, | | (Local/Docker | | Pydantic) | | state, EventLog)| | /Remote) | +------^-------+ +--------^--------+ +-------^-------+ | | | | uses | persists / streams | executes v v v +-------+ +----------+ +---------------+ | LLM | | EventLog | | bash, python | |+Cond. | +----------+ | jupyter, | +-------+ | browser, FS | +---------------+ def step(self, conversation, on_event, on_token=None) -> None: state = conversation.state # 1. Drain confirmed actions waiting to execute. pending = ConversationState.get_unmatched_actions(state.events) if pending: self._execute_actions(conversation, pending, on_event) return # 2. Honor any UserPromptSubmit hook that wants to block the message. if state.last_user_message_id is not None: reason = state.pop_blocked_message(state.last_user_message_id) if reason is not None: state.execution_status = ConversationExecutionStatus.FINISHED return # 3. Build the LLM prompt — may return a Condensation event instead. msgs_or_cond = prepare_llm_messages( state.events, condenser=self.condenser, llm=self.llm) if isinstance(msgs_or_cond, Condensation): on_event(msgs_or_cond); return # 4. Call the LLM with retry. try: response = make_llm_completion( self.llm, msgs_or_cond, tools=list(self.tools_map.values()), on_token=on_token) except LLMContextWindowExceedError: if self.condenser and self.condenser.handles_condensation_requests(): on_event(CondensationRequest()); return raise # 5. Classify and dispatch. match classify_response(response.message): case LLMResponseType.TOOL_CALLS: self._handle_tool_calls(...) case LLMResponseType.CONTENT: self._handle_content_response(...) case LLMResponseType.REASONING_ONLY | LLMResponseType.EMPTY: self._handle_no_content_response(...) def step(self, conversation, on_event, on_token=None) -> None: state = conversation.state # 1. Drain confirmed actions waiting to execute. pending = ConversationState.get_unmatched_actions(state.events) if pending: self._execute_actions(conversation, pending, on_event) return # 2. Honor any UserPromptSubmit hook that wants to block the message. if state.last_user_message_id is not None: reason = state.pop_blocked_message(state.last_user_message_id) if reason is not None: state.execution_status = ConversationExecutionStatus.FINISHED return # 3. Build the LLM prompt — may return a Condensation event instead. msgs_or_cond = prepare_llm_messages( state.events, condenser=self.condenser, llm=self.llm) if isinstance(msgs_or_cond, Condensation): on_event(msgs_or_cond); return # 4. Call the LLM with retry. try: response = make_llm_completion( self.llm, msgs_or_cond, tools=list(self.tools_map.values()), on_token=on_token) except LLMContextWindowExceedError: if self.condenser and self.condenser.handles_condensation_requests(): on_event(CondensationRequest()); return raise # 5. Classify and dispatch. match classify_response(response.message): case LLMResponseType.TOOL_CALLS: self._handle_tool_calls(...) case LLMResponseType.CONTENT: self._handle_content_response(...) case LLMResponseType.REASONING_ONLY | LLMResponseType.EMPTY: self._handle_no_content_response(...) def step(self, conversation, on_event, on_token=None) -> None: state = conversation.state # 1. Drain confirmed actions waiting to execute. pending = ConversationState.get_unmatched_actions(state.events) if pending: self._execute_actions(conversation, pending, on_event) return # 2. Honor any UserPromptSubmit hook that wants to block the message. if state.last_user_message_id is not None: reason = state.pop_blocked_message(state.last_user_message_id) if reason is not None: state.execution_status = ConversationExecutionStatus.FINISHED return # 3. Build the LLM prompt — may return a Condensation event instead. msgs_or_cond = prepare_llm_messages( state.events, condenser=self.condenser, llm=self.llm) if isinstance(msgs_or_cond, Condensation): on_event(msgs_or_cond); return # 4. Call the LLM with retry. try: response = make_llm_completion( self.llm, msgs_or_cond, tools=list(self.tools_map.values()), on_token=on_token) except LLMContextWindowExceedError: if self.condenser and self.condenser.handles_condensation_requests(): on_event(CondensationRequest()); return raise # 5. Classify and dispatch. match classify_response(response.message): case LLMResponseType.TOOL_CALLS: self._handle_tool_calls(...) case LLMResponseType.CONTENT: self._handle_content_response(...) case LLMResponseType.REASONING_ONLY | LLMResponseType.EMPTY: self._handle_no_content_response(...) # Drop in DockerWorkspace, no code change anywhere else. from openhands.workspace import DockerWorkspace with DockerWorkspace(host_port=8010, extra_ports=True) as ws: conversation = Conversation(agent=agent, workspace=ws) conversation.send_message("Refactor the auth module.") conversation.run() # Drop in DockerWorkspace, no code change anywhere else. from openhands.workspace import DockerWorkspace with DockerWorkspace(host_port=8010, extra_ports=True) as ws: conversation = Conversation(agent=agent, workspace=ws) conversation.send_message("Refactor the auth module.") conversation.run() # Drop in DockerWorkspace, no code change anywhere else. from openhands.workspace import DockerWorkspace with DockerWorkspace(host_port=8010, extra_ports=True) as ws: conversation = Conversation(agent=agent, workspace=ws) conversation.send_message("Refactor the auth module.") conversation.run() LLMSummarizingCondenser(llm=summarizer_llm, max_size=80, keep_first=4) LLMSummarizingCondenser(llm=summarizer_llm, max_size=80, keep_first=4) LLMSummarizingCondenser(llm=summarizer_llm, max_size=80, keep_first=4) def maybe_condense(events, summarizer, max_size=80, keep_first=4): if len(events) <= max_size: return events head = events[:keep_first] tail = events[-(max_size // 2):] middle = events[keep_first:-(max_size // 2)] summary = summarizer.complete( "Summarize the following agent history concisely, preserving " "decisions, findings, and current state:\n" + dump(middle)) return head + [SummaryEvent(text=summary)] + tail def maybe_condense(events, summarizer, max_size=80, keep_first=4): if len(events) <= max_size: return events head = events[:keep_first] tail = events[-(max_size // 2):] middle = events[keep_first:-(max_size // 2)] summary = summarizer.complete( "Summarize the following agent history concisely, preserving " "decisions, findings, and current state:\n" + dump(middle)) return head + [SummaryEvent(text=summary)] + tail def maybe_condense(events, summarizer, max_size=80, keep_first=4): if len(events) <= max_size: return events head = events[:keep_first] tail = events[-(max_size // 2):] middle = events[keep_first:-(max_size // 2)] summary = summarizer.complete( "Summarize the following agent history concisely, preserving " "decisions, findings, and current state:\n" + dump(middle)) return head + [SummaryEvent(text=summary)] + tail --- name: kubernetes trigger: type: keyword keywords: ["kubernetes", "k8s", "kubectl"] --- # Kubernetes guidance - Always use `kubectl --context=<ctx>` explicitly. - Current cluster: !`kubectl config current-context` - Common namespaces: !`kubectl get ns -o name | head -10` --- name: kubernetes trigger: type: keyword keywords: ["kubernetes", "k8s", "kubectl"] --- # Kubernetes guidance - Always use `kubectl --context=<ctx>` explicitly. - Current cluster: !`kubectl config current-context` - Common namespaces: !`kubectl get ns -o name | head -10` --- name: kubernetes trigger: type: keyword keywords: ["kubernetes", "k8s", "kubectl"] --- # Kubernetes guidance - Always use `kubectl --context=<ctx>` explicitly. - Current cluster: !`kubectl config current-context` - Common namespaces: !`kubectl get ns -o name | head -10` - 💡 TL;DR — what OpenHands is, in one paragraph - 1. 🧠 The mental model — Agent / Conversation / Workspace / Event Stream - 2. ⚙️ The agent loop — the canonical 30 lines - 3. 🔄 Actions and Observations — the universal protocol - 4. 📡 The Event Stream — single source of truth - 5. 🐳 Sandboxing — Workspace + Action Execution Server - 6. 🗜️ Memory — the Condenser - 7. 🔌 Microagents / Skills — knowledge that auto-loads - 8. 🤖 Sub-agent delegation — parallel agents on a shared workspace - 9. 🚨 Stuck detection — the "agent has lost the plot" alarm - 10. 🔒 Security — confirmation policy + risk analyzer - 11. 🌐 The LLM layer — LiteLLM, Router, and prompt caching - 12. 🚀 What makes OpenHands highly autonomous — synthesis - 13. 🏗️ Building your own — minimum viable autonomous agent - 14. 🏭 Production features OpenHands ships that you'll want eventually - 15. ⚠️ Honest pitfalls and gotchas - 16. 📚 Reading list (curated, in order) - 17. 🎯 Closing — the mental model that makes everything click - 💻 Code is the universal action. Don't design 20 bespoke tools. Give the agent bash + Python + a file editor + a browser, then let it write code. - 📦 State lives in one place. All components are immutable Pydantic models. The only mutable thing is ConversationState. This makes the system replayable, debuggable, and safe to parallelize. - 🔄 Observations close the loop. Every error, stderr, exit code, and HTTP response goes back into the next prompt. Self-correction is not a feature — it's a side effect of letting the LLM see its own consequences. - Agent — pure function from history → next Action. No state of its own. Configured by LLM, a list of Tools, a Condenser, optional MCP config, and system_prompt_kwargs. - Conversation — owns ConversationState, drives the loop, persists the EventLog, and is the only mutable thing in the system. - Workspace — knows how to execute commands and shuttle files. Three implementations: in-process (LocalWorkspace), container (DockerWorkspace), or HTTP (RemoteAPIWorkspace). Same agent code; just swap the workspace. - Event — every interaction is an event: MessageEvent, ActionEvent, ObservationEvent, AgentErrorEvent, Condensation, etc. The event log is append-only and the single source of truth — replaying it reconstructs the entire conversation. - Optional isolation, not mandatory sandboxing. The agent runs in-process by default; you swap LocalWorkspace → DockerWorkspace for isolation without changing any agent code. Don't make sandboxing a build-time decision. - Stateless components, single source of truth. Agent, Tool, LLM, and Condenser are immutable Pydantic models. The only mutable thing in the entire system is ConversationState. State changes happen by appending events — never by mutating objects. - Strict separation of concerns. The SDK never imports applications. The CLI, GUI, GitHub resolver, and your custom integration all consume the SDK as a library. This sounds obvious; it is not what V0 did. - Two-layer composability. Compose at package level (swap workspaces, swap servers) and at component level (swap tools, prompts, condensers, LLMs). Both layers exist intentionally. - Drain pending actions (confirmation flow). - Block if a hook rejected the user message. - Prepare prompt — condenser may decide to summarize first. - Call the LLM, with explicit handling for context-window overflow. - Dispatch the response: tool call → execute, plain text → emit message, empty → ask the LLM to try again. - The LLM never "remembers" what it did — it sees the entire event log every step. That's why the EventLog has to be cheap to materialize. - The error in step 3 is what triggered the next action. The agent didn't have to be told "if a test fails, read it" — that came from the LLM reasoning over the observation. - Steps 8–9 are verification, not optimism. A well-prompted agent re-runs tests after editing. That's what stops it from declaring victory on broken code (more on this in §3). - Exploration — read the repo, find relevant files, understand the surface area before doing anything. (grep, find, cat, ls.) - Analysis — form a hypothesis about what to change and why. The ThinkTool exists specifically for this — it produces no observation, it just gives the model a slot to reason without committing to an action. - Implementation — make the smallest change that addresses the analysis. Prefer editing existing files over creating duplicates. Don't write README.md unless asked. Don't commit secrets. - Verification — re-run the tests, lints, build. Loop back to analysis if it fails. Only call finish when verification passes. - RunCommand(command: str) — bash via subprocess or docker exec. - EditFile(path: str, old: str, new: str) — string-replace editor (much more reliable for LLMs than full-file rewrites). - Finish(summary: str) — terminate. - Append-only — events are never edited, only superseded by a Condensation event that marks ranges as "forgotten." - Persisted incrementally — each event is one JSON file; full state is rebuildable from disk. - Pub/sub for V0 (EventStream.subscribe(...)) or read by auxiliary services for V1. - a persistent tmux bash session (so cd and shell history survive across actions), - a persistent IPython kernel (%pip install once, use forever), - a Playwright Chromium browser, - a str-replace file editor with undo. - Build a Docker image with bash, python, your project deps, and a tiny FastAPI server. - The server has one endpoint: POST /exec taking {kind: "bash"|"python", body: "..."}. - Use tmux for bash persistence (or just keep a subprocess.Popen open and write into its stdin). - Mount the workspace dir as a volume. - Stream output back chunked so the agent can show progress. - Add a watchdog: kill anything running over N seconds. - Proactive — View.from_events() checks size on each step. - Reactive — when the LLM raises LLMContextWindowExceedError, the agent emits a CondensationRequest event and tries again next step. - !`shell command` — run a command at activation time and inline the output (e.g. !git branch --show-current`` to inject current branch into the prompt). - mcp_tools: block in the YAML — spin up an MCP server when this skill activates, register its tools dynamically. - Repository skills auto-discover AGENTS.md / CLAUDE.md / GEMINI.md in the repo root. - Spawn — register sub-agents by name, optionally with custom prompts and tool subsets. Each sub-agent inherits the parent's LLM and shares the workspace, but has its own independent EventLog. - Delegate — dispatch one or more named sub-agents in parallel threads. Block until all complete. Return a consolidated result. - Risk analyzer (openhands.sdk.security) — every Action gets a SecurityRisk ∈ {LOW, MEDIUM, HIGH, UNKNOWN} score. The default LLMSecurityAnalyzer adds a security_risk field to every tool's JSON schema, so the LLM scores its own action inline with no extra call. The MCP tool annotations (readOnlyHint, destructiveHint, etc.) feed in. - Confirmation policy — AlwaysConfirm, NeverConfirm, or ConfirmRisky(threshold=HIGH). With ConfirmRisky, low-risk actions auto-execute; risky ones pause the conversation in WAITING_FOR_CONFIRMATION until the user approves. - Stores secrets per-session, late-bound (resolved only at exec time). - Masks them in stdout/stderr (<secret-hidden>). - Encrypts at rest, supports rotation, supports callable resolvers (refresh tokens, etc.). - The TerminalTool scans commands for known secret keys, exports them as env vars, and replaces matches in output. - Two completion modes: classic Chat Completions (function calling) and OpenAI's Responses API (for GPT-5 reasoning models). Auto-detected per-model from a model_features.py registry. - Reasoning/thinking blocks are first-class. Anthropic extended thinking is captured as ThinkingBlocks; OpenAI reasoning items as ReasoningItemModel. The agent persists these on ActionEvent/MessageEvent (reasoning_content, thinking_blocks) so they're replayable and can be fed back to the model on the next turn — required to maintain reasoning continuity for o-series and Sonnet thinking-mode. - NonNativeToolCallingMixin — for models without native function calling, it serializes tools into a structured prompt and parses responses with regex. Lets even small open-source models drive the agent loop. The pattern: detect, then either call native function-calling or fall back to prompt-and-parse — same agent code path. - RouterLLM — abstract base; subclass with select_llm(messages) -> str. Real example: route image-containing messages to a vision model and text-only to a cheap model. Composes recursively (a router can route to a router), so you can build cost-optimization trees. - Prompt caching — Anthropic cache_control breakpoints inserted at stable prefix points (system prompt, tool defs, condensed history). Big savings on long conversations. (V0 had a known caching bug; V1 fixed it — verify in your own implementation that your cache hit rate is what you expect.) - Telemetry — every call records tokens in/out, computed cost, latency, error counts. Cost shows up at conversation.state.stats.accumulated_cost. - Retries with exponential backoff baked in. - Original OpenDevin paper: CodeActAgent v1.8 on Claude 3.5 Sonnet hit 26% on SWE-Bench Lite at $1.10 per instance. That's the cost-per-task baseline for a previous-generation model on a hard benchmark. - V1 paper: the default condenser claims to cut API spend by ~2× on long sessions with no measurable quality loss. - Trivial task (few file edits, no tests): $0.05–$0.30 per run on a frontier model. - SWE-Bench-style real fix (explore + analyze + edit + verify): $0.50–$3 per task. - Multi-hour autonomous run (resolver mode on a complex issue): $5–$30, easily more without a condenser. - A retry wrapper. - A cost tracker (pull prompt_tokens/completion_tokens off the response, multiply by your rate card; if the model returns reasoning tokens, account for them separately — they're often billed differently). - A response classifier: did the model call a tool, return text, return reasoning only, or return nothing? Branch explicitly. - A loop with no human in the middle by default. Conversation.run() doesn't ask permission — it runs until FinishAction, stuck detection, budget exhaustion, or explicit pause. Headless mode hard-codes this. - Self-correction via observations. Every error becomes an Observation in the next prompt. The LLM literally sees its own stderr and adjusts. - Long-horizon memory. The condenser lets sessions exceed the context window indefinitely. A persistent EventLog means full replay even after compression. - Tool diversity = "anything a developer can do." Bash + Python + browser + file edit + MCP. The agent isn't shoehorned into 5 narrow operations. - Microagents/Skills. Conventions and project knowledge load automatically when triggered. The agent "knows" your project the moment it lands in the repo. - Sub-agent delegation. Parallel exploration with isolated contexts. Big tasks decompose without the parent context blowing up. - Stuck detection. Five semantic patterns, every step. Pathological loops die early. - Budget controls. Max iterations, max retries, accumulated-cost tracking. Hard ceilings on runaway spend. - Risk-aware confirmation policy. ConfirmRisky lets the agent fly through routine work and pause only on destructive ops. - Replayable event log. When the agent screws up, you can rewind to any event and try a different model or prompt. Debug loops are short. - Same code, multiple isolation levels. LocalWorkspace for dev, DockerWorkspace for prod. No code changes — meaning you actually use isolation in prod, instead of half-disabling it for "dev convenience." - End-to-end resolver mode. The GitHub Action wires GitHub issue → sandbox → CodeActAgent → PR. No human in the loop. This is the maximum-autonomy configuration in production. - Events + EventLog. Define Event, ActionEvent, ObservationEvent, MessageEvent. Append-only list, JSON-serializable, persistable. - Tools: bash + finish. Two Pydantic action models, two executor classes. Use subprocess.Popen for bash; keep stdin open for persistence. - LLM wrapper. LiteLLM call + retry + cost tracking. Function-calling tool format. - Agent.step(). Build messages from events, call LLM, classify response, dispatch. Copy the 5-phase shape from §2. - Conversation.run(). while not finished: agent.step(). - LocalWorkspace. Dirt simple: cwd plus a tool registry. - First end-to-end test. Give it "create a hello world Python script and run it". It should succeed. - File edit tool. str_replace_editor semantics — read, then replace exact string. Refuse if the string doesn't appear or appears more than once. - DockerWorkspace. Build a small image. Run a FastAPI server inside that exposes POST /exec. Forward bash and file-edit actions over HTTP. - Condenser. Threshold check + LLM-summarize-the-middle. Cache summaries. - Skills loader. Parse .agents/skills/*.md, evaluate triggers, inject into system prompt. - Stuck detector. Sliding window + hash compare. Halt on repeats. - Security gate. Add a risk field to tool schemas; pause when risk ≥ HIGH unless the user pre-approved. - Sub-agent delegation tool. ThreadPoolExecutor over child Conversations sharing the workspace. - Don't build a UI first. A CLI that prints events as they happen is enough to develop against. Headless mode is the actual product anyway. - Don't write a controller class. It's just while not done: agent.step(). Adding ceremony hurts. - Don't build a mock workspace. Use the real one (subprocess + cwd) from day 1. Mocks lie. - Do log every prompt and response to disk. When the agent does something weird, you'll need to see exactly what it saw. - Do use Pydantic for every event. Schemas catch 80% of bugs at the boundary. - Do measure tokens and cost from step 3. Otherwise you'll get a $400 bill the first time you run an overnight loop. - Browser automation (real browsing is hard; cover 90% of cases with curl/Python requests from bash). - MCP integration (YAGNI until your tools outgrow the built-ins). - Multi-agent delegation (single agent + good condenser handles surprisingly long tasks). - Streaming. (Token streaming is a UI feature, not an autonomy feature.) - The default condenser is aggressive (max_size=80, keep_first=4). Long sessions trigger it often. Real cost savings vary by workload. - Stuck detection thresholds are conservative (4+ identical pairs). An agent can burn meaningful tokens in a near-loop before being killed. Tune thresholds for your tolerance. - Headless mode = always-approve = blast radius is whatever the workspace allows. Always use Docker in headless. Don't mount more than the working directory. - 77% on SWE-Bench Verified is Claude Sonnet 4.5 dependent. Cheaper models drop hard (Qwen3 Coder 480B was 65%; smaller models do worse). The architecture isn't magic. - The V0 → V1 split (Nov 2025) means a lot of public material describes a different codebase. The original arXiv paper describes V0; the new V1 paper and the SDK repo describe the architecture this guide focuses on. When you read OpenHands content, check the date. - MCP integration is powerful but adds attack surface. External MCP servers run with the agent's privileges. Treat them like dependencies — pin and audit. - Browsing is the flakiest tool. Site changes, JS-heavy pages, and bot detection make it unreliable. Reach for curl or library-level integrations whenever you can. - OpenHands V1 SDK paper (arXiv 2511.03690) — the canonical architecture writeup. Read this first. - Original OpenDevin paper (arXiv 2407.16741) — context on CodeAct and the original design. - Agent.step() source in openhands-sdk/openhands/sdk/agent/agent.py — the loop, in 100 lines. - Architecture overview docs — how the pieces fit. - Skill format — the autonomy multiplier. - Stuck detector guide — the loop-prevention patterns. - Sub-agent delegation guide — parallel agents. - CodeActAgent system prompt — actual prompt text. - Headless mode docs — the autonomous configuration. - GitHub Action / Resolver — issue → PR pipeline. - "Function" → stateless Agent. - "Event history" → append-only EventLog. - "Next event" → Action, executed by Workspace, producing Observation. - "Run in a loop" → Conversation, until Finish or stuck.