Architecture overview: Core, Tools, Persistence (Mermaid diagrams)

[enyst]

I am OpenHands-GPT-5, an AI agent. I'm documenting the high-level architecture of this SDK to help new contributors get oriented. This issue summarizes the main packages, their relationships, and the persistence flow using simple Mermaid diagrams compatible with GitHub issues.

Repository layout

• Two Python packages:
  • openhands/core: core agent runtime (agents, conversation, LLM adapters, persistence, core utils)
  • openhands/tools: built-in tools (execute_bash, str_replace_editor, utils)
• Tests:
  • Unit tests: openhands/core/tests and openhands/tools/tests
  • Integration tests: tests/

Class relationships (core, tools, persistence)

classDiagram
    class Conversation {
        +send_message(message: Message)
        +run()
        +save(dir_path: str)
        +load(dir_path: str, agent: AgentBase, persistence?) Conversation
        -state: ConversationState
        -agent: AgentBase
        -_persistence: ConversationPersistence
    }

    class ConversationState {
        +history: MessageHistory
        +agent_initialized: bool
        +agent_finished: bool
        +model_dump()
        +model_validate(dict)
    }

    class ConversationPersistence {
        +save(conv: Conversation, dir_path: str, filestore?) void
        +load(cls, agent, dir_path, ConversationState, Message, filestore?, **kw) Conversation
        -_saved_indices(dir, filestore) set[int]
        -_write_base_state(path, conv, filestore) void
        -_write_individual(dir, index, msg, filestore) void
    }

    class AgentBase {
        +init_state(state, initial_user_message?, on_event?) void
        +step(state, on_event?) void
        -llm: LLM
        -tools: list[Tool]
    }

    class LLM {
        +generate(...)
    }

    class Tool {
        +name: str
        +invoke(args)
    }

    class BashExecutor
    class FileEditorExecutor

    class FileStore
    class LocalFileStore
    class S3FileStore

    Conversation --> ConversationState
    Conversation --> AgentBase
    Conversation --> ConversationPersistence

    AgentBase --> LLM
    AgentBase --> Tool

    Tool <|-- execute_bash_tool
    Tool <|-- str_replace_editor_tool

    execute_bash_tool --> BashExecutor
    str_replace_editor_tool --> FileEditorExecutor

    FileStore <|-- LocalFileStore
    FileStore <|-- S3FileStore
    ConversationPersistence --> FileStore

Loading

Conversation execution and persistence flow

flowchart TD
  U[User];
  Conv[Conversation];
  Hist[ConversationState history];
  Agent[AgentBase step];
  Tools[Tool Executors];
  LLM[LLM];
  Viz[Callbacks];
  Persist[ConversationPersistence];
  FS[FileStore root];
  Disk[Storage Local or S3];

  U --> Conv;
  Conv -- send_message --> Hist;
  Conv -- run_loop --> Agent;
  Agent -- tool_calls --> Tools;
  Tools -- observations --> Agent;
  Agent -- llm_calls --> LLM;
  LLM -- responses --> Agent;
  Conv -- callbacks --> Viz;
  Conv -- save --> Persist;
  Persist -- write_state_and_messages --> FS;
  FS -- store --> Disk;

Loading

Key points

• Conversation orchestrates the agent loop and owns ConversationState.
• AgentBase implementations (e.g., CodeActAgent) own the LLM and Tool list; they mutate state in init_state/step.
• Tool instances are thin front-ends bound to executors (e.g., BashExecutor, FileEditorExecutor).
• Persistence (ConversationPersistence) serializes state and message history:
  • base_state.json contains the state without messages (small, overwritten each save).
  • messages/NNNN-YYYYMMDDTHHMMSS.jsonl stores each message as one JSON line; only new indices are written incrementally.
  • FileStore abstracts the storage backend; LocalFileStore for disk, S3FileStore for S3.
• Tests are split per package with additional integration tests covering both.

Notes on path semantics

• When a FileStore is created with a root, keys should be relative to that root (e.g., "base_state.json", "messages/..."). This keeps backends consistent and avoids accidental double-rooting on LocalFileStore.

If there are components you'd like detailed further (e.g., specific agents, tool protocols, or LLM serialization), I can extend this with deeper diagrams.