Core concepts · Module 5
Architecture fundamentals
State is everything your agent needs to remember to complete its task.
Previously
Design patterns
For complex tasks, planning before acting often works better than interleaved reasoning.
This module
Architecture fundamentals
State is everything your agent needs to remember to complete its task.
Next
Core concepts practice test
Test recall and judgement against the governed stage question bank before you move on.
Progress
Mark this module complete when you can explain it without rereading every paragraph.
Why this matters
""" Agent State Management ====================== Immutable state for reliable agent operation.
What you will be able to do
- 1 Explain what state is in an agent and why it matters.
- 2 Design a control flow that can route, retry, and stop safely.
- 3 Handle errors and edge cases without losing the goal.
Before you begin
- Foundations-level understanding of this course
- Confidence with key terms introduced in Stage 1
Common ways people get this wrong
- Accidental data exposure. If the agent can reach sensitive data by default, it will leak it eventually.
- No safe failure. If everything depends on the agent being perfect, the system is not production ready.
Main idea at a glance
Agent State Structure
Stage 1
User Input
The incoming message or command that starts the agent
2.5.1 Agent State Management
State is everything your agent needs to remember to complete its task.
"""
Agent State Management
======================
Immutable state for reliable agent operation.
"""
from dataclasses import dataclass, field
from typing import List, Dict, Any, Optional
from datetime import datetime
from enum import Enum
class AgentStatus(Enum):
"""Current state of the agent."""
IDLE = "idle"
THINKING = "thinking"
ACTING = "acting"
WAITING = "waiting"
COMPLETE = "complete"
ERROR = "error"
@dataclass(frozen=True)
class AgentState:
"""
Immutable agent state.
Using frozen=True ensures state cannot be accidentally modified.
Each operation creates a new state object.
"""
messages: tuple = field(default_factory=tuple)
status: AgentStatus = AgentStatus.IDLE
current_step: int = 0
max_steps: int = 10
tool_results: tuple = field(default_factory=tuple)
error: Optional[str] = None
metadata: Dict[str, Any] = field(default_factory=dict)
def with_message(self, role: str, content: str) -> "AgentState":
"""Return new state with added message."""
new_messages = self.messages + ({"role": role, "content": content},)
return AgentState(
messages=new_messages,
status=self.status,
current_step=self.current_step,
max_steps=self.max_steps,
tool_results=self.tool_results,
error=self.error,
metadata=self.metadata.copy()
)
def with_status(self, status: AgentStatus) -> "AgentState":
"""Return new state with updated status."""
return AgentState(
messages=self.messages,
status=status,
current_step=self.current_step,
max_steps=self.max_steps,
tool_results=self.tool_results,
error=self.error,
metadata=self.metadata.copy()
)
def with_tool_result(self, tool: str, result: Any) -> "AgentState":
"""Return new state with added tool result."""
new_results = self.tool_results + ({"tool": tool, "result": result},)
return AgentState(
messages=self.messages,
status=self.status,
current_step=self.current_step + 1,
max_steps=self.max_steps,
tool_results=new_results,
error=self.error,
metadata=self.metadata.copy()
)
def is_complete(self) -> bool:
"""Check if agent has finished."""
return self.status in (AgentStatus.COMPLETE, AgentStatus.ERROR)
def should_continue(self) -> bool:
"""Check if agent should keep going."""
return (
not self.is_complete()
and self.current_step < self.max_steps
)2.5.2 Error Handling
Agents will fail. The question is how gracefully.
2.5.3 Model selection and cost governance
Model selection is partly an economic decision, but pricing pages move too quickly for a fixed table in course notes to stay trustworthy.
How to control model cost without guessing
Treat pricing as a live operational input, not a memorised fact.
-
Match the model to the task
Start with the smallest model that meets the quality and risk threshold for the job.
-
Measure total request cost
Include retrieval, retries, tool calls, and output length, not only the headline token rate.
-
Route by policy
Send simple, low-risk tasks to a cheaper path and escalate only when the workflow genuinely needs stronger reasoning or human review.
-
Verify vendor pricing live
Use the official pricing page before budgeting or signing off an architecture decision, because tiers and discounts can change.
Stage 2 Assessment
This checkpoint follows the architecture and reasoning sections. Use it to confirm that you can explain the ReAct loop, choose tool boundaries, and distinguish recoverable errors from stop conditions.
Summary
In this stage, you have learned:
The ReAct pattern: How agents interleave reasoning with action
Tools and actions: How to design, validate, and execute agent tools
Memory management: Short-term, long-term, and semantic memory
Design patterns: When to use ReAct, Plan-and-Execute, and Reflection
Architecture fundamentals: State management and error handling
Mental model
Boundaries make systems safe
A good architecture makes boundaries explicit so tools and data do not leak across them.
-
1
User interface
-
2
Agent service
-
3
Policy and guards
-
4
Tool services
-
5
Data stores
Assumptions to keep in mind
- Trust boundaries are enforced. A boundary in a diagram is useless if the code path ignores it.
- Least privilege is real. Tool permissions should match the task, not the developer's convenience.
Failure modes to notice
- Accidental data exposure. If the agent can reach sensitive data by default, it will leak it eventually.
- No safe failure. If everything depends on the agent being perfect, the system is not production ready.
Check yourself
Quick check. Architecture fundamentals
0 of 4 opened
What is agent state in plain terms
Everything the agent needs to carry forward so it can stay coherent and finish the task.
Why is a max step limit a useful safety control
It prevents runaway loops and bounded costs when something goes wrong.
Scenario. A tool returns invalid input. What is a calm, user friendly response
Ask for clarification, explain what is missing, and show a safe example of the expected format.
What is the difference between a recoverable and terminal error
Recoverable errors can be retried or worked around. Terminal errors mean the agent should stop and report safely.
Module 2.1-2.2: Thinking and Tools Quiz
0 of 5 opened
What does ReAct stand for?
Correct answer: Reasoning and Acting
ReAct stands for Reasoning and Acting. It is a pattern where agents interleave explicit reasoning (thoughts) with actions (tool use) and observations (results).
What is the purpose of the Observation step in ReAct?
Correct answer: To provide the tool result back to the reasoning process
The Observation step provides the result of a tool action back to the agent's reasoning process. This new information feeds into the next Thought, allowing the agent to adjust its approach.
What makes a good tool description?
Correct answer: Being specific about what the tool does and when to use it
Good tool descriptions are specific about what the tool does, when to use it, what it returns, and any limitations. This helps the agent select the right tool.
Why is tool input validation important?
Correct answer: Because agent-generated inputs cannot be trusted
Agent-generated inputs cannot be fully trusted. The agent might hallucinate impossible parameters, generate malicious inputs, or simply make mistakes. Always validate before executing.
What is an infinite loop in agent terms?
Correct answer: When the agent keeps repeating the same action without making progress
An infinite loop occurs when the agent keeps repeating the same action, never reaching an answer. This usually happens with ambiguous stopping conditions or when the agent gets stuck.
Module 2.3-2.5: Memory and Architecture Quiz
0 of 5 opened
What is the difference between short-term and long-term memory?
Correct answer: Short-term is lost when the session ends, long-term persists
Short-term memory holds information during a single conversation and is lost when the session ends. Long-term memory persists across sessions, storing preferences, facts, and history.
What is a context window?
Correct answer: The maximum text an LLM can process at once
The context window is the maximum amount of text an LLM can process at once. For a 128K token window, roughly 96,000 words. Anything beyond this limit is not seen by the model.
What is a vector database used for in AI agents?
Correct answer: Semantic search - finding things by meaning
Vector databases store information as numerical vectors. Similar items have similar vectors, allowing semantic search: finding things by meaning, not just keywords.
When should you use the Plan-and-Execute pattern?
Correct answer: For complex multi-step tasks with clear goals
Plan-and-Execute works best for complex multi-step tasks. The agent creates a plan first, then executes steps sequentially. This is better than ReAct for tasks requiring coordinated steps.
Why should agent state be immutable?
Correct answer: To prevent accidental modifications and enable debugging
Immutable state prevents accidental modifications that can cause bugs. Each operation creates a new state, making it easy to track changes and debug issues.
Artefact and reflection
Artefact
A small architecture sketch you can reuse in later builds.
Reflection
Where in your work would explain what state is in an agent and why it matters. change a decision, and what evidence would make you trust that change?
Optional practice
Write down the state fields your agent must keep to stay correct.