Skip to slide
004 / 221

CH 01 · Anatomy of an AI Agent · 04/12

Read as one page

Real code: Hermes Agent assembles all six parts in one function

Hermes Agent, a large Python agent from Nous Research, builds an AIAgent by sending its constructor arguments to one function, init_agent. AIAgent.__init__ forwards those arguments except the deprecated tool_delay, which it ignores after a warning. Read init_agent top to bottom and you can point at the line that installs each part: the iteration budget the loop will consult, the model client, the tool list, the session store, memory, and the context engine. The loop itself is in another file, and several of these helpers are not named after the part.

def init_agent(
    agent, base_url: str | None = None, api_key: str | None = None, provider: str | None = None, api_mode: str | None = None,
    # ... (37 lines: the rest of the keyword parameters, from UI callbacks to chat identity)
):
    # ... (16 lines: safe-worker overrides; copy plain settings onto the agent)
    agent.iteration_budget = iteration_budget or IterationBudget(max_iterations)  # [1]
    # ... (28 lines: provider name, capabilities, credential pool)
    _resolve_api_mode(agent, api_mode, provider_name, base_url)  # [2]
    _finalize_routing(agent, api_mode, credential_pool)
    # ... (22 lines: UI callbacks, request overrides, prompt-cache settings)
    _setup_logging(agent)
    _set_defaults(agent, _STREAM_STATE)
    _build_client(agent, api_key, base_url, fallback_model)  # [3]
    _init_fallback_chain(agent, fallback_model)
    _load_tools(agent, enabled_toolsets, disabled_toolsets)  # [4]
    _init_session_state(  # [5]
        agent, session_id, session_db, parent_session_id, reasoning_config, max_tokens,
        checkpoints_enabled, checkpoint_max_snapshots, checkpoint_max_total_size_mb, checkpoint_max_file_size_mb,
    )
    # ... (9 lines: read the config file once; apply display settings)
    _init_memory(agent, _agent_cfg, skip_memory, platform, memory_manager=memory_manager)  # [6]
    # ... (5 lines: parse compression settings; work out the model's context length)
    _build_context_engine(agent, _agent_cfg, cs, _custom_providers, _effective_context_length, session_db)  # [7]

Source: NousResearch/hermes-agent, agent/agent_init.py (MIT)

What to notice

  1. [1] The loop's limit. IterationBudget is a thread-safe counter of loop iterations, not of raw model calls. A turn whose only tool was execute_code (the model writes a program that calls tools) is refunded, and so is an iteration that gets restarted. On a normal iteration, begin_iteration calls consume() before the model request. If that returns False, the turn stops with reason budget_exhausted. If _budget_grace_call is set, that iteration skips consume() and clears the flag, so the model gets one more call after the budget is spent. The parameter default for max_iterations is sys.maxsize. The terminal UI passes a configured cap instead, 500 when the config omits one.
  2. [2] The model, part one. _resolve_api_mode walks an ordered list of rules, first match wins, and stores api_mode, the request format this provider speaks, such as chat_completions or anthropic_messages. _finalize_routing, the next call, can still change that choice, including upgrading chat_completions to codex_responses (OpenAI's Responses API) when the caller did not set a format.
  3. [3] The model, part two. _build_client creates the client for that format. _init_fallback_chain stores an ordered list of backup models, tried when the primary one is exhausted.
  4. [4] The tools. _load_tools asks the tool registry for definitions, filtered by enabled and disabled toolsets (named groups of tools), and keeps them on agent.tools.
  5. [5] The surrounding system. A session ID, an optional SQLite session store, and file checkpoints. Logging was set up a few lines earlier, before the model client exists.
  6. [6] The memory. File-based memory, plus an external memory plugin if one is configured.
  7. [7] The context. The context engine compacts the conversation once input crosses a configured fraction of the window. The default fraction is 50 percent, and a window under 512,000 tokens is raised to at least 75 percent.

Read it yourself: in run_agent.py, name the argument AIAgent.__init__ drops. In _init_memory, if memory fails to load, does the agent still start? In turn_iteration_prep.py, which iteration skips consume()?

Finished this idea?

Your learning progress stays in this browser.