Principle:Neuml Txtai Agent Configuration
| Knowledge Sources | |
|---|---|
| Domains | NLP, Agent, Tool_Use |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
Agent Configuration is the principle of declaratively specifying the components of an autonomous AI agent -- the language model, available tools, execution method, prompt template, and memory settings -- through a unified keyword-argument interface that the Agent constructor translates into a ready-to-run agent process.
Description
Building an autonomous agent requires assembling several moving parts: a language model for reasoning, a set of tools for acting, an execution strategy for orchestrating the reasoning-action loop, optional memory for multi-turn context, and optional instructions to guide behaviour. The Agent Configuration principle establishes a single constructor, Agent.__init__, as the convergence point where all these concerns are resolved.
The constructor accepts three explicit parameters and an open **kwargs dictionary:
- template -- an optional Jinja2 template string that must contain {{ text }} and {{ memory }} placeholders. This controls how the user's query and any prior conversation history are rendered into the final prompt.
- memory -- an optional integer specifying how many prior (request, response) pairs to retain. When set, a collections.deque with the given maxlen is initialised.
- **kwargs -- all remaining arguments are forwarded to ProcessFactory.create, which handles model instantiation, tool creation, and agent-process construction.
Key arguments expected in kwargs include:
- method -- either "code" (using CodeAgent, which generates and executes Python) or "toolcalling" / None (using ToolCallingAgent, which emits structured tool-call actions). This determines the smolagents backend.
- model or llm -- a model path string or a dictionary of LLM configuration. This is wrapped in a PipelineModel that bridges txtai's LLM pipeline to the smolagents Model interface.
- tools -- a list of tool specifications processed by ToolFactory.create (see the Tool Assembly principle).
- max_steps -- the maximum number of reasoning-action iterations before the agent is forced to produce a final answer.
- instructions -- either inline text or a path to an agents.md file containing system-level guidance prepended to the agent prompt.
The constructor also maintains backward compatibility by translating the deprecated max_iterations key to max_steps.
After construction, the agent exposes:
- self.process -- the underlying smolagents agent (CodeAgent or ToolCallingAgent) that executes the reasoning loop.
- self.tools -- a dictionary of registered tools for introspection.
- self.memory -- the deque (or None) holding conversation history.
Usage
Use Agent Configuration when:
- You are setting up a new autonomous agent and need to specify model, tools, and execution strategy in a single call.
- You want to enable multi-turn memory so the agent can reference prior interactions.
- You need to customise the prompt template to inject domain-specific context or formatting.
- You want to provide system-level instructions (inline or from a file) to constrain agent behaviour.
- You are migrating from an older txtai agent configuration that uses max_iterations instead of max_steps.
Theoretical Basis
1. Declarative Configuration
Rather than requiring procedural code to wire together an LLM, tools, and an execution loop, the Agent constructor accepts a flat dictionary of configuration. This makes it straightforward to drive agent creation from YAML files, API payloads, or configuration management systems.
2. Inversion of Control
The Agent class does not directly instantiate models or tools. It delegates to ProcessFactory and ToolFactory, which encapsulate the creation logic. This inversion of control keeps the Agent class focused on orchestration (prompting and memory) while factories handle the mechanical assembly.
3. Multi-Turn Memory as a Sliding Window
Agent memory is implemented as a bounded deque, which automatically discards the oldest entries when the capacity is exceeded. This provides a simple but effective sliding-window context mechanism that prevents unbounded prompt growth.
The construction flow can be visualised as:
Agent.__init__(template, memory, **kwargs)
|
+-> ProcessFactory.create(kwargs)
| |
| +-> PipelineModel(model_config) # wraps LLM
| +-> ToolFactory.create(kwargs) # builds tool list
| +-> CodeAgent | ToolCallingAgent # smolagents backend
|
+-> self.process = agent_backend
+-> self.tools = agent_backend.tools
+-> self.memory = deque(maxlen=memory) or None