Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt

Use this file to discover all available pages before exploring further.

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. Source: openhands-sdk/openhands/sdk/agent/

​
Core Responsibilities

The Agent system has four primary responsibilities:
  1. Reasoning-Action Loop - Query LLM to generate next actions based on conversation history
  2. Tool Orchestration - Select and execute tools, handle results and errors
  3. Context Management - Apply skills, manage conversation history via condensers
  4. Security Validation - Analyze proposed actions for safety before execution via security analyzer

​
Architecture

​
Key Components

ComponentPurposeDesign
AgentMain implementationStateless reasoning-action loop executor
AgentBaseAbstract base classDefines agent interface and initialization
AgentContextContext containerManages skills, prompts, and metadata
CondenserHistory compressionReduces context when token limits approached
SecurityAnalyzerSafety validationEvaluates action risk before execution

​
Reasoning-Action Loop

The agent operates through a single-step execution model where each step() call processes one reasoning cycle: Step Execution Flow:
  1. Pending Actions: If actions awaiting confirmation exist, execute them and return
  2. Condensation: If condenser exists:
    • Call condenser.condense() with current event view
    • If returns View: use condensed events for LLM query (continue in same step)
    • If returns Condensation: emit event and return (will be processed next step)
  3. LLM Query: Query LLM with messages from event history
    • If context window exceeded: emit CondensationRequest and return
  4. Response Parsing: Parse LLM response into events
    • Tool calls → create ActionEvent(s)
    • Text message → create MessageEvent and return
  5. Confirmation Check: If actions need user approval:
    • Set conversation status to WAITING_FOR_CONFIRMATION and return
  6. Action Execution: Execute tools and create ObservationEvent(s)
Key Characteristics:
  • Stateless: Agent holds no mutable state between steps
  • Event-Driven: Reads from event history, writes new events
  • Interruptible: Each step is atomic and can be paused/resumed

​
Agent Context

The agent applies AgentContext which includes skills and prompts to shape LLM behavior:
Skill TypeActivationUse Case
repoAlways includedProject-specific context, conventions
knowledgeTrigger words/patternsDomain knowledge, special behaviors
Review this guide for details on creating and applying agent context and skills.

​
Tool Execution

Tools follow a strict action-observation pattern: Execution Modes:
ModeBehaviorUse Case
DirectExecute immediatelyDevelopment, trusted environments
ConfirmationStore as pending, wait for user approvalHigh-risk actions, production
Security Integration: Before execution, the security analyzer evaluates each action:
  • Low Risk: Execute immediately
  • Medium Risk: Log warning, execute with monitoring
  • High Risk: Block execution, request user confirmation

​
Component Relationships

​
How Agent Interacts

Relationship Characteristics:
  • Conversation → Agent: Orchestrates step execution, provides event history
  • Agent → LLM: Queries for next actions, receives tool calls or messages
  • Agent → Tools: Executes actions, receives observations
  • AgentContext → Agent: Injects skills and prompts into LLM queries

​
See Also