My Secret to Building Reliable AI Agents

Hey everyone, Alex here from agntai.net. Hope you’re all having a productive week. Today, I want to talk about something that’s been on my mind a lot lately, especially as I’ve been wrestling with a few client projects that involve making AI agents… well, less flaky. We’ve all seen the flashy demos, the “AI does X in Y seconds!” videos, but in the trenches, building reliable, production-ready AI agents is a whole different ballgame. And a big part of that, I’ve found, comes down to how we think about their architecture, particularly when it comes to managing their internal state.

Forget the hype for a moment. What truly makes an AI agent useful isn’t just its ability to generate a plausible response or execute a single task. It’s its capacity to maintain context, learn from interactions, and adapt its behavior over time – essentially, to have a memory and use it effectively. This isn’t just about storing a chat history; it’s about storing and retrieving structured information that informs future decisions, plans, and actions. And frankly, a lot of the initial agent architectures I see people building (and, full disclosure, that I’ve built myself in the past) fall short here. They treat state management as an afterthought, leading to agents that forget crucial details, repeat themselves, or get stuck in loops.

The State of Agent State: Why It’s a Mess (Sometimes)

Think about a typical interaction with an early-stage AI agent. You tell it something, it responds. You tell it something else, it might forget what you said two messages ago. Why? Often, it’s because the agent’s “memory” is simply a prompt buffer. Every new turn, the entire conversation history (or a truncated version) is re-fed to the LLM. This works okay for short interactions, but it’s incredibly inefficient, expensive, and fragile for anything more complex. It’s like trying to remember everything you’ve ever learned by re-reading all your textbooks every morning. Exhausting, right?

My own “aha!” moment came during a project for an internal support agent. The goal was to build an AI that could help engineers debug issues by asking clarifying questions, looking up documentation, and suggesting solutions. Early iterations were a disaster. The agent would ask for a log file, then two turns later, ask for the *same* log file again. Or it would propose a solution that was already tried and failed, because it hadn’t properly stored the “failed attempts” in its memory. I was basically building a very polite, very expensive goldfish.

The problem wasn’t the LLM’s intelligence; it was the lack of a structured, accessible, and updatable internal state. We needed something more robust than just stuffing everything into a prompt.

Moving Beyond Prompt Buffers: Structured State Management

The solution, or at least a significant step towards it, lies in treating an AI agent’s internal state not as a flat list of tokens, but as a structured, queryable knowledge base. This means moving away from simply passing a long string of text around and instead, thinking about what discrete pieces of information the agent needs to track, how those pieces relate, and how they can be updated or retrieved efficiently.

Here’s how I started approaching it, breaking it down into a few key components:

1. Explicitly Defining State Schemas

Just like you’d define data models for a traditional application, you need to define what an agent *knows* about its current task, the user, the environment, and its own progress. This isn’t just for the agent’s benefit; it’s also crucial for us, the developers, to understand and debug its behavior.

For my support agent, I started by defining a simple schema for an ongoing “debugging session”:

• `issue_description`: What’s the user’s problem? (string)
• `current_hypothesis`: What does the agent think is going on? (string)
• `steps_tried`: A list of {action: string, outcome: string, timestamp: datetime}
• `relevant_docs`: A list of document IDs or URLs consulted (list of strings)
• `asked_for_logs`: Boolean (has the agent requested logs?)
• `log_file_received`: String (the actual log content, if provided)
• `follow_up_questions`: List of strings (questions the agent still needs to ask)

This simple structure immediately made a huge difference. Instead of asking “Did I ask for logs?” by scanning a long conversation history, the agent could just check a boolean flag. Instead of trying to infer what was tried, it could query a structured list.

2. The “State Manager” Module

This is the core piece. It’s not just about *what* the state is, but *how* it’s updated and accessed. I usually build a dedicated module or class whose sole responsibility is to manage this internal state. It acts as the single source of truth for the agent’s memory.

class DebuggingSessionState:
 def __init__(self, session_id):
 self.session_id = session_id
 self.issue_description = ""
 self.current_hypothesis = ""
 self.steps_tried = [] # List of dicts: {'action': '', 'outcome': '', 'timestamp': ''}
 self.relevant_docs = []
 self.asked_for_logs = False
 self.log_file_received = ""
 self.follow_up_questions = []
 self.status = "active" # active, resolved, blocked

 def update_issue_description(self, description):
 self.issue_description = description

 def add_step_tried(self, action, outcome):
 self.steps_tried.append({
 'action': action,
 'outcome': outcome,
 'timestamp': datetime.now().isoformat()
 })

 def set_asked_for_logs(self, value: bool):
 self.asked_for_logs = value

 def get_state_summary(self) -> str:
 # This is where the LLM gets its structured context
 summary = f"Issue: {self.issue_description}\n"
 summary += f"Current Hypothesis: {self.current_hypothesis}\n"
 if self.steps_tried:
 summary += "Steps tried:\n"
 for step in self.steps_tried:
 summary += f"- {step['action']} (Outcome: {step['outcome']})\n"
 if self.asked_for_logs:
 summary += "Logs have been requested.\n"
 if self.log_file_received:
 summary += "Logs received and processed.\n"
 return summary

 # ... more update and getter methods

This `DebuggingSessionState` class is where all the session-specific information lives. The agent’s control flow (which might be another LLM call, or a rule-based system) interacts with this object to get the latest context and to record new information.

3. Information Extraction and State Update (The LLM’s Role)

Now, how do we get information *into* this structured state? This is where the LLM comes back into play, but in a more focused role: information extraction and state transformation. Instead of asking the LLM to generate the *next turn* of the conversation directly, we ask it to analyze the user’s input and its own generated actions, and then propose updates to the internal state.

Here’s a simplified flow:

1. User input arrives.
2. The LLM receives the user input + a prompt asking it to identify key entities, intentions, and potential state updates based on the `DebuggingSessionState` schema.
3. The LLM outputs a structured JSON object representing proposed state changes.
4. A “state update agent” (could be a simple Python function or another small LLM call) validates these proposed changes and applies them to the `DebuggingSessionState` object.
5. The agent’s control flow then consults the *updated* `DebuggingSessionState` to decide the next action (e.g., generate a response, call a tool, ask a clarifying question).

A prompt for step 2 might look something like this:

You are an AI assistant helping to update the state of a debugging session.
The current state is:
{current_state_summary_from_get_state_summary_method}

The user just said: "{user_input}"

Based on the user's input, propose updates to the session state.
If the user provided a log file, set `log_file_received` to the content.
If the user described their issue, update `issue_description`.
If they mentioned a step they already tried, add it to `steps_tried`.
If no changes are needed, return an empty JSON object.

Output only a JSON object with the proposed changes.
Example:
{{
 "issue_description": "New description of the problem.",
 "steps_tried": [
 {{"action": "Checked network config", "outcome": "No issues found"}}
 ],
 "log_file_received": "..."
}}

The LLM’s output might then be parsed by your `StateUpdateAgent` function:

import json

def apply_llm_state_updates(session_state: DebuggingSessionState, llm_output_json: str):
 try:
 updates = json.loads(llm_output_json)
 if 'issue_description' in updates:
 session_state.update_issue_description(updates['issue_description'])
 if 'steps_tried' in updates:
 for step in updates['steps_tried']:
 session_state.add_step_tried(step['action'], step['outcome'])
 if 'log_file_received' in updates:
 session_state.log_file_received = updates['log_file_received']
 # ... handle other fields
 except json.JSONDecodeError as e:
 print(f"Error parsing LLM state update: {e}")
 except Exception as e:
 print(f"Error applying state update: {e}")

This approach has several advantages:

• Reduced Context Window Pressure: The full, verbose conversation history doesn’t need to be passed with every LLM call. Only a concise, structured summary of the *relevant* state is provided.
• Improved Consistency: The agent is less likely to forget or contradict itself because its memory is explicitly stored and updated.
• Easier Debugging: You can inspect the `DebuggingSessionState` object at any point to understand exactly what the agent “knows.” This was a lifesaver for me.
• Modularity: The state management logic is separated from the core reasoning logic, making both easier to develop and maintain.
• Tool Integration: When the agent calls tools, their outcomes can directly update the state. For example, if a “lookup_docs” tool returns relevant documentation, those doc IDs can be added to `relevant_docs`.

4. Persistent Storage for Long-Running Sessions

For agents that need to operate over extended periods (days, weeks), this in-memory `DebuggingSessionState` object needs to be persisted. This is standard software engineering stuff: dump it to a database (SQL or NoSQL), a file, or a key-value store. The key is that the structure defined in step 1 makes this persistence straightforward.

When a session resumes, you just load the saved state back into your `DebuggingSessionState` object.

Beyond Simple Schemas: Graph-Based State

While the simple schema works well for many tasks, for more complex agents that deal with highly interconnected information (e.g., knowledge graphs, complex planning scenarios), a more sophisticated state representation might be needed. I’ve dabbled with using small, embedded graph databases (like DuckDB with a graph extension, or even just a dictionary representing an adjacency list) to store relationships between entities the agent discovers. The LLM then becomes an “entity and relationship extractor,” populating this graph, which can then be queried using more traditional graph traversal algorithms.

For example, if an agent is helping a user plan a trip, its state might include nodes for “city,” “hotel,” “activity,” and edges for “has_flight_to,” “is_located_in,” “booked_at.” This allows for much richer reasoning than a flat list.

Actionable Takeaways for Your Next Agent Project

If you’re building an AI agent, please, for the love of all that is stable and debuggable, don’t just rely on a prompt buffer for memory. Here’s what I recommend:

1. Design Your Agent’s State Early: Before you even write the first prompt, think about what discrete pieces of information your agent needs to track. Sketch out a simple schema.
2. Build a Dedicated State Manager: Create a class or module responsible for holding, updating, and providing access to your agent’s internal state.
3. Use LLMs for Extraction, Not Just Generation: Leverage your LLM to extract structured information from user inputs and its own actions, and use that to update the state. This is a more focused, reliable use of the LLM.
4. Summarize State for Context: When you do need to provide context to an LLM for reasoning or generation, provide a concise, structured summary of the *relevant parts* of the current state, not the entire conversation history.
5. Persist Everything (If Needed): For long-running agents, make sure your structured state can be easily saved and reloaded.
6. Start Simple, Iterate: Don’t try to build a complex graph database from day one. Start with a simple Python dictionary or class for your state, and evolve it as your agent’s needs grow.

Building reliable AI agents is less about finding the magic prompt and more about sound software engineering principles applied to a new paradigm. State management is perhaps the most critical of these principles. Get it right, and your agents will be smarter, more consistent, and a lot less frustrating to develop. Trust me, your future self (and your clients) will thank you.

That’s it for this week! Let me know in the comments if you’ve had similar experiences or if you have other strategies for managing agent state. I’m always keen to hear what’s working for others in the field.

🕒 Published: May 4, 2026