Skip to content

Commit ff3de90

Browse files
committed
rename org to OpenHands
1 parent 5992131 commit ff3de90

14 files changed

Lines changed: 1546 additions & 102 deletions

‎sdk/arch/agent-server.mdx‎

Lines changed: 540 additions & 0 deletions
Large diffs are not rendered by default.

‎sdk/arch/agent.mdx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: High-level architecture of the reasoning-action loop
55

66
The **Agent** component implements the core reasoning-action loop that drives autonomous task execution. It orchestrates LLM queries, tool execution, and context management through a stateless, event-driven architecture.
77

8-
**Source:** [`openhands-sdk/openhands/sdk/agent/`](https://github.com/All-Hands-AI/agent-sdk/tree/main/openhands-sdk/openhands/sdk/agent)
8+
**Source:** [`openhands-sdk/openhands/sdk/agent/`](https://github.com/OpenHands/agent-sdk/tree/main/openhands-sdk/openhands/sdk/agent)
99

1010
## Core Responsibilities
1111

@@ -58,11 +58,11 @@ flowchart TB
5858

5959
| Component | Purpose | Design |
6060
|-----------|---------|--------|
61-
| **[`Agent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/agent.py)** | Main implementation | Stateless reasoning-action loop executor |
62-
| **[`AgentBase`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/base.py)** | Abstract base class | Defines agent interface and initialization |
63-
| **[`AgentContext`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/agent_context.py)** | Context container | Manages skills, prompts, and metadata |
64-
| **[`Condenser`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/)** | History compression | Reduces context when token limits approached |
65-
| **[`SecurityAnalyzer`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/)** | Safety validation | Evaluates action risk before execution |
61+
| **[`Agent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/agent.py)** | Main implementation | Stateless reasoning-action loop executor |
62+
| **[`AgentBase`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/agent/base.py)** | Abstract base class | Defines agent interface and initialization |
63+
| **[`AgentContext`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/agent_context.py)** | Context container | Manages skills, prompts, and metadata |
64+
| **[`Condenser`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/)** | History compression | Reduces context when token limits approached |
65+
| **[`SecurityAnalyzer`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/security/)** | Safety validation | Evaluates action risk before execution |
6666

6767
## Reasoning-Action Loop
6868

‎sdk/arch/condenser.mdx‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: High-level architecture of the conversation history compression sys
55

66
The **Condenser** system manages conversation history compression to keep agent context within LLM token limits. It reduces long event histories into condensed summaries while preserving critical information for reasoning. For more details, read the [blog here](https://openhands.dev/blog/openhands-context-condensensation-for-more-efficient-ai-agents).
77

8-
**Source:** [`openhands-sdk/openhands/sdk/context/condenser/`](https://github.com/All-Hands-AI/agent-sdk/tree/main/openhands-sdk/openhands/sdk/context/condenser)
8+
**Source:** [`openhands-sdk/openhands/sdk/context/condenser/`](https://github.com/OpenHands/agent-sdk/tree/main/openhands-sdk/openhands/sdk/context/condenser)
99

1010
## Core Responsibilities
1111

@@ -67,13 +67,13 @@ flowchart TB
6767

6868
| Component | Purpose | Design |
6969
|-----------|---------|--------|
70-
| **[`CondenserBase`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)** | Abstract interface | Defines `condense()` contract |
71-
| **[`RollingCondenser`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)** | Rolling window base | Implements threshold-based triggering |
72-
| **[`LLMSummarizingCondenser`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/llm_summarizing_condenser.py)** | LLM summarization | Uses LLM to generate summaries |
73-
| **[`NoOpCondenser`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/no_op_condenser.py)** | No-op implementation | Returns view unchanged |
74-
| **[`PipelineCondenser`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/pipeline_condenser.py)** | Multi-stage pipeline | Chains multiple condensers |
75-
| **[`View`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/view.py)** | Event view | Represents history for LLM |
76-
| **[`Condensation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condensation event | Metadata about compression |
70+
| **[`CondenserBase`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)** | Abstract interface | Defines `condense()` contract |
71+
| **[`RollingCondenser`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/base.py)** | Rolling window base | Implements threshold-based triggering |
72+
| **[`LLMSummarizingCondenser`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/llm_summarizing_condenser.py)** | LLM summarization | Uses LLM to generate summaries |
73+
| **[`NoOpCondenser`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/no_op_condenser.py)** | No-op implementation | Returns view unchanged |
74+
| **[`PipelineCondenser`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/condenser/pipeline_condenser.py)** | Multi-stage pipeline | Chains multiple condensers |
75+
| **[`View`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/view.py)** | Event view | Represents history for LLM |
76+
| **[`Condensation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condensation event | Metadata about compression |
7777

7878
## Condenser Types
7979

@@ -249,7 +249,7 @@ flowchart TB
249249
4. **Condensation Creation:** Create `Condensation` event with `forgotten_event_ids` and summary
250250
5. **Return to Agent:** Condenser returns `Condensation` (not `View`)
251251
6. **History Update:** Agent adds `Condensation` to event log and exits step
252-
7. **Next Step:** `View.from_events()` ([source](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/view.py)) processes Condensation to filter events and insert summary
252+
7. **Next Step:** `View.from_events()` ([source](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/context/view.py)) processes Condensation to filter events and insert summary
253253

254254
## View and Condensation
255255

‎sdk/arch/conversation.mdx‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: High-level architecture of the conversation orchestration system
55

66
The **Conversation** component orchestrates agent execution through structured message flows and state management. It serves as the primary interface for interacting with agents, managing their lifecycle from initialization to completion.
77

8-
**Source:** [`openhands-sdk/openhands/sdk/conversation/`](https://github.com/All-Hands-AI/agent-sdk/tree/main/openhands-sdk/openhands/sdk/conversation)
8+
**Source:** [`openhands-sdk/openhands/sdk/conversation/`](https://github.com/OpenHands/agent-sdk/tree/main/openhands-sdk/openhands/sdk/conversation)
99

1010
## Core Responsibilities
1111

@@ -61,15 +61,15 @@ flowchart LR
6161

6262
| Component | Purpose | Design |
6363
|-----------|---------|--------|
64-
| **[`Conversation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py)** | Unified entrypoint | Returns correct implementation based on workspace type |
65-
| **[`LocalConversation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py)** | Local execution | Runs agent directly in process |
66-
| **[`RemoteConversation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py)** | Remote execution | Delegates to agent-server via HTTP/WebSocket |
67-
| **[`ConversationState`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py)** | State container | Pydantic model with validation and serialization |
68-
| **[`EventLog`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/event_store.py)** | Event storage | Immutable append-only store with efficient queries |
64+
| **[`Conversation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py)** | Unified entrypoint | Returns correct implementation based on workspace type |
65+
| **[`LocalConversation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py)** | Local execution | Runs agent directly in process |
66+
| **[`RemoteConversation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py)** | Remote execution | Delegates to agent-server via HTTP/WebSocket |
67+
| **[`ConversationState`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py)** | State container | Pydantic model with validation and serialization |
68+
| **[`EventLog`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/event_store.py)** | Event storage | Immutable append-only store with efficient queries |
6969

7070
## Factory Pattern
7171

72-
The [`Conversation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py) class automatically selects the correct implementation based on workspace type:
72+
The [`Conversation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/conversation.py) class automatically selects the correct implementation based on workspace type:
7373

7474
```mermaid
7575
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%%
@@ -182,11 +182,11 @@ The conversation system provides pluggable services that operate independently o
182182

183183
| Service | Purpose | Architecture Pattern |
184184
|---------|---------|---------------------|
185-
| **[Event Log](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/event_store.py)** | Append-only immutable storage | Event sourcing with indexing |
186-
| **[Persistence](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py)** | Auto-save & resume | Debounced writes, incremental events |
187-
| **[Stuck Detection](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/stuck_detector.py)** | Loop prevention | Sliding window pattern matching |
188-
| **[Visualization](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/visualizer.py)** | Execution diagrams | Event stream → visual representation |
189-
| **[Secrets Manager](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/secrets_manager.py)** | Secure value storage | Memory-only with masked logging |
185+
| **[Event Log](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/event_store.py)** | Append-only immutable storage | Event sourcing with indexing |
186+
| **[Persistence](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/state.py)** | Auto-save & resume | Debounced writes, incremental events |
187+
| **[Stuck Detection](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/stuck_detector.py)** | Loop prevention | Sliding window pattern matching |
188+
| **[Visualization](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/visualizer.py)** | Execution diagrams | Event stream → visual representation |
189+
| **[Secrets Manager](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/secrets_manager.py)** | Secure value storage | Memory-only with masked logging |
190190

191191
**Design Principle:** Services read from the event log but never mutate state directly. This enables:
192192
- Services can be enabled/disabled independently

‎sdk/arch/design.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ V0 relied on mutable Python objects and dynamic typing, which led to silent inco
3131
**V1 Principle:**
3232
**Keep everything stateless, with exactly one mutable state.**
3333
All components (agents, tools, LLMs, and configurations) are immutable Pydantic models validated at construction.
34-
The only mutable entity is the [conversation state](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_state.py), a single source of truth that enables deterministic replay and robust persistence across sessions or distributed systems.
34+
The only mutable entity is the [conversation state](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_state.py), a single source of truth that enables deterministic replay and robust persistence across sessions or distributed systems.
3535

3636
## Clear Boundaries between Agent and Applications
3737

‎sdk/arch/events.mdx‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: High-level architecture of the typed event framework
55

66
The **Event System** provides an immutable, type-safe event framework that drives agent execution and state management. Events form an append-only log that serves as both the agent's memory and the integration point for auxiliary services.
77

8-
**Source:** [`openhands-sdk/openhands/sdk/event/`](https://github.com/All-Hands-AI/agent-sdk/tree/main/openhands-sdk/openhands/sdk/event)
8+
**Source:** [`openhands-sdk/openhands/sdk/event/`](https://github.com/OpenHands/agent-sdk/tree/main/openhands-sdk/openhands/sdk/event)
99

1010
## Core Responsibilities
1111

@@ -63,20 +63,20 @@ flowchart TB
6363

6464
| Component | Purpose | Design |
6565
|-----------|---------|--------|
66-
| **[`Event`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/base.py)** | Base event class | Immutable Pydantic model with ID, timestamp, source |
67-
| **[`LLMConvertibleEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/base.py)** | LLM-compatible events | Abstract class with `to_llm_message()` method |
68-
| **[`MessageEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/message.py)** | Text messages | User or assistant conversational messages with skills |
69-
| **[`ActionEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/action.py)** | Tool calls | Agent tool invocations with thought, reasoning, security risk |
70-
| **[`ObservationBaseEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Tool response base | Base for all tool call responses |
71-
| **[`ObservationEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Tool results | Successful tool execution outcomes |
72-
| **[`UserRejectObservation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | User rejection | User rejected action in confirmation mode |
73-
| **[`AgentErrorEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Agent errors | Errors from agent/scaffold (not model output) |
74-
| **[`SystemPromptEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/system.py)** | System context | System prompt with tool schemas |
75-
| **[`CondensationSummaryEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condenser summary | LLM-convertible summary of forgotten events |
76-
| **[`ConversationStateUpdateEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_state.py)** | State updates | Key-value conversation state changes |
77-
| **[`Condensation`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condensation result | Events being forgotten with optional summary |
78-
| **[`CondensationRequest`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Request compression | Trigger for conversation history compression |
79-
| **[`PauseEvent`](https://github.com/All-Hands-AI/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/user_action.py)** | User pause | User requested pause of agent execution |
66+
| **[`Event`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/base.py)** | Base event class | Immutable Pydantic model with ID, timestamp, source |
67+
| **[`LLMConvertibleEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/base.py)** | LLM-compatible events | Abstract class with `to_llm_message()` method |
68+
| **[`MessageEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/message.py)** | Text messages | User or assistant conversational messages with skills |
69+
| **[`ActionEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/action.py)** | Tool calls | Agent tool invocations with thought, reasoning, security risk |
70+
| **[`ObservationBaseEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Tool response base | Base for all tool call responses |
71+
| **[`ObservationEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Tool results | Successful tool execution outcomes |
72+
| **[`UserRejectObservation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | User rejection | User rejected action in confirmation mode |
73+
| **[`AgentErrorEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py)** | Agent errors | Errors from agent/scaffold (not model output) |
74+
| **[`SystemPromptEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/system.py)** | System context | System prompt with tool schemas |
75+
| **[`CondensationSummaryEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condenser summary | LLM-convertible summary of forgotten events |
76+
| **[`ConversationStateUpdateEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_state.py)** | State updates | Key-value conversation state changes |
77+
| **[`Condensation`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Condensation result | Events being forgotten with optional summary |
78+
| **[`CondensationRequest`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/condenser.py)** | Request compression | Trigger for conversation history compression |
79+
| **[`PauseEvent`](https://github.com/OpenHands/agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/user_action.py)** | User pause | User requested pause of agent execution |
8080

8181
## Event Types
8282

0 commit comments

Comments
 (0)