Thanks to visit codestin.com
Credit goes to docs.openhands.dev

Skip to main content

​
class Agent

Bases: AgentBase Main agent implementation for OpenHands. The Agent class provides the core functionality for running AI agents that can interact with tools, process messages, and execute actions. It inherits from AgentBase and implements the agent execution logic.

​
Example

>>> from openhands.sdk import LLM, Agent, Tool
>>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key"))
>>> tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")]
>>> agent = Agent(llm=llm, tools=tools)

​
Properties

  • agent_context: AgentContext | None
  • condenser: CondenserBase | None
  • filter_tools_regex: str | None
  • llm: LLM
  • mcp_config: dict[str, Any]
  • model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
  • security_policy_filename: str
  • system_prompt_filename: str
  • system_prompt_kwargs: dict[str, object]
  • tools: list[Tool]

​
Methods

​
init_state()

Initialize the empty conversation state to prepare the agent for user messages. Typically this involves adding system message NOTE: state will be mutated in-place.

​
model_post_init()

This function is meant to behave like a BaseModel method to initialise private attributes. It takes context as an argument since that’s what pydantic-core passes when calling it.
  • Parameters:
    • self – The BaseModel instance.
    • context – The context.

​
step()

Taking a step in the conversation. Typically this involves:
  1. Making a LLM call
  2. Executing the tool
  3. Updating the conversation state with
LLM calls (role=”assistant”) and tool results (role=”tool”) 4.1 If conversation is finished, set state.execution_status to FINISHED 4.2 Otherwise, just return, Conversation will kick off the next step If the underlying LLM supports streaming, partial deltas are forwarded to on_token before the full response is returned. NOTE: state will be mutated in-place.

​
class AgentBase

Bases: DiscriminatedUnionMixin, ABC Abstract base class for OpenHands agents. Agents are stateless and should be fully defined by their configuration. This base class provides the common interface and functionality that all agent implementations must follow.

​
Properties

  • agent_context: AgentContext | None
  • condenser: CondenserBase | None
  • filter_tools_regex: str | None
  • llm: LLM
  • mcp_config: dict[str, Any]
  • model_config: ClassVar[ConfigDict] = (configuration object) Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
  • name: str Returns the name of the Agent.
  • prompt_dir: str Returns the directory where this class’s module file is located.
  • security_policy_filename: str
  • system_message: str Compute system message on-demand to maintain statelessness.
  • system_prompt_filename: str
  • system_prompt_kwargs: dict[str, object]
  • tools: list[Tool]
  • tools_map: dictstr, [ToolDefinition] Get the initialized tools map. :raises RuntimeError: If the agent has not been initialized.

​
Methods

​
get_all_llms()

Recursively yield unique base-class LLM objects reachable from self.
  • Returns actual object references (not copies).
  • De-dupes by id(LLM).
  • Cycle-safe via a visited set for all traversed objects.
  • Only yields objects whose type is exactly LLM (no subclasses).
  • Does not handle dataclasses.

​
init_state()

Initialize the empty conversation state to prepare the agent for user messages. Typically this involves adding system message NOTE: state will be mutated in-place.

​
model_dump_succint()

Like model_dump, but excludes None fields by default.

​
model_post_init()

This function is meant to behave like a BaseModel method to initialise private attributes. It takes context as an argument since that’s what pydantic-core passes when calling it.
  • Parameters:
    • self – The BaseModel instance.
    • context – The context.

​
resolve_diff_from_deserialized()

Return a new AgentBase instance equivalent to persisted but with explicitly whitelisted fields (e.g. api_key) taken from self.
  • Parameters:
    • persisted – The persisted agent from the conversation state.
    • events – Optional event sequence to scan for used tools if tool names don’t match. Only scanned when needed (O(n) fallback).

​
abstractmethod step()

Taking a step in the conversation. Typically this involves:
  1. Making a LLM call
  2. Executing the tool
  3. Updating the conversation state with
LLM calls (role=”assistant”) and tool results (role=”tool”) 4.1 If conversation is finished, set state.execution_status to FINISHED 4.2 Otherwise, just return, Conversation will kick off the next step If the underlying LLM supports streaming, partial deltas are forwarded to on_token before the full response is returned. NOTE: state will be mutated in-place.