CH 01 · Anatomy of an AI Agent · 04/12
Read as one pageReal 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] The loop's limit.
IterationBudgetis a thread-safe counter of loop iterations, not of raw model calls. A turn whose only tool wasexecute_code(the model writes a program that calls tools) is refunded, and so is an iteration that gets restarted. On a normal iteration,begin_iterationcallsconsume()before the model request. If that returnsFalse, the turn stops with reasonbudget_exhausted. If_budget_grace_callis set, that iteration skipsconsume()and clears the flag, so the model gets one more call after the budget is spent. The parameter default formax_iterationsissys.maxsize. The terminal UI passes a configured cap instead, 500 when the config omits one. - [2] The model, part one.
_resolve_api_modewalks an ordered list of rules, first match wins, and storesapi_mode, the request format this provider speaks, such aschat_completionsoranthropic_messages._finalize_routing, the next call, can still change that choice, including upgradingchat_completionstocodex_responses(OpenAI's Responses API) when the caller did not set a format. - [3] The model, part two.
_build_clientcreates the client for that format._init_fallback_chainstores an ordered list of backup models, tried when the primary one is exhausted. - [4] The tools.
_load_toolsasks the tool registry for definitions, filtered by enabled and disabled toolsets (named groups of tools), and keeps them onagent.tools. - [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] The memory. File-based memory, plus an external memory plugin if one is configured.
- [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.