Proposal: Minimal Python SDK

[rbren]

The Problem

There are many different ways to run OpenHands today:

• The UI
• The CLI
• Headless mode
• Python code (sorta)
• The evaluation pipeline

Worse, each of these has its own way of configuring OpenHands

• config.toml (for headless, CLI, and some of the UI)
• Settings page (for UI)
• Python args (for python)
• Flags (for CLI)
• Environment variables (for all of the above)

Even worse, all of our specific implementations for things like runtimes and web browsing are tightly coupled to the existing project, so our dependency tree is out of control.

The Solution

We need a single, deterministic, lightweight way of running OpenHands. Something that doesn’t pull from global state (like env vars and external files). Something you can install in 2 minutes. Something that Does What It Says.

Claude Code is a good example here—it’s a tightly packaged, self-contained agent, which can be deployed and run in a wide variety of contexts.

To fix this, we’ll publish an official Python SDK—a set of APIs for working with OpenHands primitives: Agents, Runtimes, LLMs, Conversations, etc. Different clients can then manage configuration and state as they please, pulling in heavy-weight things like docker as necessary.

This will not only simplify our own development—it will empower end-users to build amazing new things.

Minimum Requirements

• Lightweight python package
  • Say, < 1GB of dependencies
  • No docker dependency
  • No browser dependency
• No reliance on global state
  • no config files
  • no environment variables
• No async
  • We’ll put each conversation in its own thread
  • Callbacks will be made in threads as well
• MCP-first
  • all tool calls are driven in MCP format
  • we can add stronger types (e.g. CmdOutputObservation) after-the-fact
• Runtime-agnostic
  • it takes in a pre-canned set of tools
  • doesn’t try to edit files or run commands itself—everything goes through tools
• Accepts the following inputs:
  • LLM configuration
  • microagents (as strings? as a directory?)
  • system prompt
  • extensions to default system prompt
  • list of tools
  • MCP server config
    • gets converted into tools
• Manages LLM interactions
• Manages the conversation state and control loop
  • Most of what’s in agent_controller.py should get pulled in here
• Manages all features related to agent behavior
  • Condensation
  • Planning
  • Security analyzer (?)

Example Code

Here’s a hello world example:

from openhands.core import LLM, Agent, Tool, ToolResult, Conversation, ConversationStatus

llm = new LLM(
  model="claude-sonnet-4",
  api_key="your_api_key_here",
)

def hello_tool(name) -> ToolResult:
  print("Hello, " + name)
  return new ToolResult()

tools = [
  new Tool(
    name="hello",
    description="Says hello",
    callback=hello_tool,
    inputSchema={'type': 'string', 'description': 'name to greet'}
  ),
]

agent = new Agent(llm=llm, tools=tools)

conversation = new Conversation(agent)
conversation.start_thread()
conversation.send_message("Say hello to 'world'")

while conversation.state.status == ConversationStatus.RUNNING:
  sleep(1)
 
if conversation.state.status == ConversationStatus.ERROR:
  raise Exception("Error!")
else:
  print("Agent finished")

Similar example, but with a LocalRuntime:

from openhands.core import LLM, Agent, Tool, Conversation, ConversationStatus
from openhands.runtime import LocalRuntime

llm = new LLM(
  model="claude-sonnet-4",
  api_key="your_api_key_here",
)

runtime = LocalRuntime()
runtime.clone_repo("All-Hands-AI/OpenHands")
runtime.run_command("echo 'do a flip' > /tmp/Plan.md")
microagents = runtime.load_microagents()

def run_lint():
  return runtime.run_command("npm run lint:fix")

tools = runtime.tools + [
  new Tool(
    name="lint",
    description="Lints files and makes automatic changes where possible",
    callback=run_lint,
  ),
]

mcp_tools = MCPClient(load_mcp_config())
tools += mcp_tools

agent = new Agent(llm=llm, tools=tools, microagents=microagents)

def print_event(evt):
  print(evt)

conversation = new Conversation(agent)
conversation.register_callback(print_event)
conversation.start_thread()
conversation.send_message("Follow /tmp/Plan.md")

while conversation.state.status == ConversationStatus.RUNNING:
  sleep(1)
 
if conversation.state.status == ConversationStatus.ERROR:
  raise Exception("Error!")
else:
  print("Agent finished")

With delegation

from openhands.core import LLM, Agent, Tool, Conversation, ConversationStatus

llm = new LLM(
  model="claude-sonnet-4",
  api_key="your_api_key_here",
)

delegate_agent = new Agent(llm=llm, tools=[])
delegate_conversations = []
def create_conversation(msg):
	conversation = new Conversation(delegate_agent)
	conversation.start_thread()
	conversation.send_message("Say hello to 'world'")
	delegate_conversations.push(conversation)

tools = [
  new Tool(
    name="create_conversation",
    description="Create new conversation",
    callback=create_conversation,
    inputSchema={'type': 'string', 'description': 'Create a new OpenHands conversation to do a subtask'}
  ),
]

base_agent = new Agent(llm=llm, tools=tools)
base_conversation = new Conversation(agent)
base_conversation.start_thread()
base_conversation.send_message("Create 3 OpenHands conversations that each flips a coin and report the results")

while conversation.state.status == ConversationStatus.RUNNING:
  sleep(1)
 
if conversation.state.status == ConversationStatus.ERROR:
  raise Exception("Error!")
else:
  print("Agent finished")

With message passing

from openhands.core import LLM, Agent, Tool, Conversation, ConversationStatus

llm = new LLM(
  model="claude-sonnet-4",
  api_key="your_api_key_here",
)

implementer_agent = new Agent(llm=llm, tools=[...])
implementer_convo = new Conversation(implementer_agent)
implementer_convo.start_thread()
implementer_convo.send_message("Build a hello world react app")

def pass_message_to_implementer(msg):
  implementer_convo.send_message(msg)

pass_message_tool = new Tool(
    name="pass_message",
    description="Says hello",
    callback=pass_message_to_implementer,
    inputSchema={'type': 'string', 'description': 'send a message to the implementer'}
)

testing_agent = new Agent(llm=llm, tools=tools + [pass_message_to_implementer_tool])
testing_convo = new Conversation(testing_agent)
implementer_convo.start_thread()
implementer_convo.send_message("Test the react app and tell the implementer about any issues.")

while implementer_convo.state.status == ConversationStatus.RUNNING or testing_convo.state.status == ConversationStatus.RUNNING:
  sleep(1)
 
if implementer_convo.state.status == ConversationStatus.ERROR:
  raise Exception("Error!")
else:
  print("Agent finished")

Classes

LLM

Maps very closely to (exact copy of?) our current LLM class.

Handles completions based on configured LLM settings.

We will keep LLMRegistry in OpenHands Server and just pass one of the LLMs into the Agent.

Methods:

• completion()

Agent

Maps very closely to (exact copy of?) the current CodeActAgent.

Contains all prompt text, and manages prompt extensions/customizations (e.g. microagents, custom system prompt)

Manages the conversion of ConversationState → Prompt → ToolCall

Methods:

• step()

Conversation

This maps pretty closely to the current AgentController class.

Probably removes delegation support.

The loop should be more iterative than event-driven. I.e. we have a while True: instead of calling step() inside of on_event()

At each step, calls agent.step(), then executes the corresponding tool call.

Methods:

• start_thread() starts a new thread which will drive the agent loop forward
• pause() prevents the agent from stepping forward further (but keeps thread alive)
• resume() allows the agent to step forward again
• close() kills the thread
• get_state()
• get_history()
• register_event_callback()
  • callbacks are in a new thread
  • events include:
    • ToolCall (fka Action)
    • ToolResult (fka Observation)

ConversationState

Exact copy of current State class.

Fully serializable and deserializable. Can rehydrate an entire Conversation from this data (possibly with a different agent/LLM/toolset/etc)

Tool

An abstraction that allows any tool to be plumbed into an agent. Tools are defined in MCP format with these attributes:

• name
• description
• inputSchema (JSON Schema)
• callback

The callback is a synchronous python function which must return a ToolResult

ToolCall

ToolCall represents a particular instance of using a tool. It corresponds most closely to the generic Action class in OpenHands, or possibly MCPAction

We’ll probably need to pull in the existing Action class and subclasses into this package for compatibility w/ e.g. existing Condenser logic.

ToolResult

ToolResult represents the output of a ToolCall. It corresponds most closely to the generic Observation class in OpenHands, or possibly MCPObservation

We’ll probably need to pull in the existing Observation class and subclasses into this package for compatibility w/ e.g. existing Condenser logic.

ToolResults use the MCP output format, with an additional meta field for extra data.

Example:

{
  "content": [
    {
      "type": "text",
      "text": "Hello world"
    }
  ],
  "meta": {
    "observationType": "CmdOutputObservation",
    "exitCode": 0
  },
  "isError": false
}

Shimming into OpenHands

All of this is for nought if we don’t actually start using it! But the transition will take some work.

Runtimes

Runtimes themselves stay exactly as they are. We’ll have a new method on base.py called get_tools() which returns a list of Tool which wrap methods like run_command and read_file

Actions and Observations

We’ll need a shim to convert Actions to ToolCalls and back.

We’ll need a shim to convert Observations to ToolResults and back.

EventStream

The EventStream goes away in the new world. Instead, the agent makes ToolCalls directly, and gets the ToolResults synchronously.

Clients can still snoop on the events by using register_event_callback() on the Conversation object.

We’ll need to continue serializing and saving the events to FileStore as the conversation progresses. But we may decide to break the old format in favor of the new ToolCall/ToolResult serialization.

Agent Loop

This will be the hardest part.

We can start with the CLI. We can probably rewrite a lot of the ugly logic we have for managing the event loop.

On the server, we’ll probably shim things in at the AgentSession level. This is where we create a Runtime and an AgentController; instead we’ll create a Runtime and a Conversation.

• https://github.com/openai/openai-agents-python?tab=readme-ov-file#quick-start

[enyst]

This is an interesting way to look at it, it's literally from the other end, than I was looking from, last time just last week.

(that one was was funny. People need --autoresume in CLI - I thought the reasonable thing to do is to make Conversation neutral, otherwise we'd introduce more ugly redundancies. So the agent tried to do so, and that lead to a 1h silent work from GPT-5 only to fix CI... ! Of course. The poor thing got dragged in the weeds because of globals on import paths and such 😭)

---

A few quick notes. In reverse order. 😂

Agent Loop

On the server, we’ll probably shim things in at the AgentSession level. This is where we create a Runtime and an AgentController; instead we’ll create a Runtime and a Conversation.

This might be the biggest problem.

• make AgentSession neutral
• make Conversation neutral
  ==> so they can be used in CLI mode naturally - or in this brave new world. 😅

Quick note: AgentSession shouldn't be tied to the web server, Session is, in reality, a WebSession, and only that one is, by definition, tied. (I have a quick rename PR somewhere, just for human brains to keep tabs on, easier)

More importantly, I think the path here goes through a refactoring to use ContextObject pattern, AppContext and RequestContext.

OH-GPT-5 has a pretty good write-up in this comment:

• Refactoring shared state/env vars to ContextObjects (with Mermaid diagrams)
• and the previous comment.

I think this is essentially the way forward here, details aside. It was trying to make it in stages, so the diagrams are an intermediate stage, just food for thought. The important point, it seems to me, is that we should make good use of FastAPI's support for app-scoped and request-scoped ContextObject pattern:

• we can refactor request-scoped vars, like user_id and its dependents, to a RequestContext that makes use of FastAPI's dependency injection mechanism
• global/shared/env state should probably go to app-scoped.

EventStream

The EventStream goes away in the new world. Instead, the agent makes ToolCalls directly, and gets the ToolResults synchronously.

This detail surprised me. The only thing in this proposal that I haven't considered before. 😅

I'm starting to wrap my head around it. In a way, it makes perfect sense. Even if it isn't going to stay this way, maybe going forward we will re-imagine what an Event is, simplifying the ... dual structure we have now. It's true it's dual (redundant) - for example, an Action contains both its "regular" properties AND the full tool call metadata; which duplicates the first.

Actions and Observations

shim to convert Actions to ToolCalls and back
shim to convert Observations to ToolResults and back

Clearly. We already have some kind of that: fn_call_converter.py, which converts from events with tool calls to events with simulated events via prompting. But this would be simpler.

Tool

Tools are defined in MCP format with these attributes:

• name
• description
• inputSchema (JSON Schema)
• callback

I actually have a PR that aims to encapsulate our current tools into a Tool class, with some inputSchema and name covered. I was thinking it was heading towards making it compatible with the MCPTool format, yes. (though I hadn't looked at the details)

• feat(codeact tools): encapsulate Bash tool as class; add Tool base; dispatch via handler (#10441) #10443

LLM

We will keep LLMRegistry in OpenHands Server and just pass one of the LLMs into the Agent.

Clearly. We made the Agent take an LLMRegistry at the moment, but it doesn't really need it: we can easily move the new LLM registration right now just before the agent/condenser/other-service is instantiated.

Methods:

• completion()

Probably! Not certainly... 😅

Funny detail: of course OpenAI couldn't help itself from breaking compatibility, so they have now a Responses API which is necessary to use/see GPT-5's reasoning. And it does appear to be stateful! Which... may break expectations of client code of completion(). 🫠

I have a PR implementing support on the fly, baked into completion() - so we can still use completion() while it actually sends the request to LiteLLM's responses() implementation of OpenAI's responses().

• Implement OpenAI Responses API adapter #10451