On this article, you’ll study the seven architectural parts that separate a production-grade agentic AI system from a demo script, and the way each suits into the agent\u2019s core suggestions loop.<\/p>\n
Subjects we’ll cowl embody:<\/p>\n
What every of the seven parts \u2014 notion, reminiscence, reasoning and planning, instrument execution, orchestration, guardrails, and observability \u2014 is particularly liable for.
\nThe place every part tends to interrupt in actual techniques, and why that part have to be stored separate from the others.
\nTargeted, runnable Python code illustrating the duty of every part in isolation.<\/p>\n
![\"The](\"https:\/\/machinelearningmastery.com\/wp-content\/uploads\/2026\/06\/MLM-Shittu-The-End-to-End-Agentic-AI-Pipeline-scaled.png\")
<\/p>\n
Introduction<\/h2>\n
Most \u201cconstruct an AI agent\u201d tutorials present a 40-line script that calls an LLM in a loop and calls it carried out. That script works superb for a demo. It doesn’t survive a second concurrent consumer, a flaky third-party API, or a process that seems to want twelve steps as an alternative of two.<\/p>\n
The hole between the demo and the manufacturing system isn\u2019t intelligent prompting. It\u2019s structure. Manufacturing agentic techniques are constructed from a constant set of interconnected parts: notion, reasoning, planning, reminiscence, instrument execution, orchestration, and guardrails. That very same part breakdown exhibits up throughout almost each severe structure writeup, survey paper, and manufacturing postmortem revealed within the final 12 months, no matter which framework or vendor is doing the writing.<\/p>\n
The loop beneath all of it’s constant: Objective \u2192 Notion \u2192 Reasoning \u2192 Planning \u2192 Motion \u2192 Commentary \u2192 Reminiscence Replace \u2192 again to Reasoning, repeating till the objective is met, a cease situation fires, or the agent decides it wants a human. This text walks by means of every bit of that loop as its personal part \u2014 what it\u2019s liable for, the place it tends to interrupt, and a targeted code excerpt that makes the duty concrete. Nothing right here is wired into one operating pipeline. Every bit is proven in isolation, which can be how it is best to cause about your individual system when deciding what it wants.<\/p>\n
The Seven Elements, at a Look<\/h2>\n
Architectural surveys converge on the identical core set: Notion, Reminiscence, Reasoning\/Planning, Device Execution, and Orchestration kind a closed suggestions loop \u2014 the cycle that truly runs, step after step. Guardrails and Observability wrap round that complete loop as cross-cutting issues fairly than steps contained in the sequence. You don\u2019t \u201cdo\u201d guardrails at step 4; guardrails sit between each proposed motion and the world, watching each step.<\/p>\n
That distinction shapes the remainder of this text. The primary 5 sections stroll by means of the loop within the order knowledge really flows by means of it. The final two sections cowl the wrapper layers that make the loop survivable as soon as actual cash, actual clients, and actual unwanted effects are concerned.<\/p>\n
Turning Uncooked Enter Into One thing the Agent Can Purpose About<\/h2>\n
Notion\u2019s job is to remodel uncooked inputs \u2014 textual content, voice, API payloads, sensor knowledge, and file uploads \u2014 right into a structured illustration that the reasoning engine can really work with. That is the part most tutorials skip totally, as a result of in a demo, \u201cthe consumer simply varieties textual content\u201d and there\u2019s nothing to normalize. Actual techniques take enter from webhooks, structured API calls, file uploads, and a number of channels concurrently, and each a kind of must land in the identical form earlier than something downstream can belief it.<\/p>\n
\n# notion.py
\n# Conditions: none past Python’s normal library
\n# Run: python notion.py
\n
\nfrom dataclasses import dataclass, subject
\nfrom typing import Any
\nfrom enum import Enum
\nimport json
\nfrom datetime import datetime, timezone
\n
\nclass InputSource(Enum):
\n USER_TEXT = “user_text”
\n WEBHOOK = “webhook”
\n FILE_UPLOAD = “file_upload”
\n
\n@dataclass
\nclass AgentInput:
\n “””
\n The normalized inner form each downstream part consumes,
\n no matter the place the uncooked enter really got here from. That is the
\n complete level of a notion layer: all the pieces previous this level
\n solely ever sees this one construction.
\n “””
\n supply: InputSource
\n content material: str
\n metadata: dict[str, Any] = subject(default_factory=dict)
\n received_at: str = subject(default_factory=lambda: datetime.now(timezone.utc).isoformat())
\n
\ndef perceive_user_text(raw_text: str) -> AgentInput:
\n “””Uncooked chat enter — the best case, but it surely nonetheless wants normalization.”””
\n return AgentInput(
\n supply=InputSource.USER_TEXT,
\n content material=raw_text.strip(),
\n metadata={“channel”: “chat”},
\n )
\n
\ndef perceive_webhook(raw_payload: str) -> AgentInput:
\n “””
\n A webhook delivers structured JSON, not plain textual content. Notion extracts
\n the half the agent ought to cause about and discards transport-level
\n noise like headers and signatures.
\n “””
\n payload = json.masses(raw_payload)
\n event_type = payload.get(“event_type”, “unknown”)
\n description = payload.get(“description”, “”)
\n return AgentInput(
\n supply=InputSource.WEBHOOK,
\n content material=f”Occasion ‘{event_type}’ acquired: {description}”,
\n metadata={“event_type”: event_type, “raw_payload”: payload},
\n )
\n
\ndef perceive_file_upload(filename: str, file_size_bytes: int, mime_type: str) -> AgentInput:
\n “””
\n A file add occasion has no natural-language content material in any respect — notion
\n has to assemble one thing the reasoning engine can really use.
\n “””
\n return AgentInput(
\n supply=InputSource.FILE_UPLOAD,
\n content material=f”Consumer uploaded file ‘{filename}’ ({mime_type}, {file_size_bytes} bytes)”,
\n metadata={“filename”: filename, “mime_type”: mime_type, “size_bytes”: file_size_bytes},
\n )
\n
\n
\nif __name__ == “__main__”:
\n text_input = perceive_user_text(” What is the standing of my refund? “)
\n webhook_input = perceive_webhook(json.dumps({
\n “event_type”: “payment_failed”,
\n “description”: “Card declined for order #4821”,
\n }))
\n file_input = perceive_file_upload(“invoice_q3.pdf”, 184320, “utility\/pdf”)
\n
\n for inp in [text_input, webhook_input, file_input]:
\n print(f”[{inp.source.value}] content material=”{inp.content material}””)
\n print(f” metadata keys: {record(inp.metadata.keys())}n”)<\/p>\n
1<\/p>\n
2<\/p>\n
3<\/p>\n
4<\/p>\n
5<\/p>\n
6<\/p>\n
7<\/p>\n
8<\/p>\n
9<\/p>\n
10<\/p>\n
11<\/p>\n
12<\/p>\n
13<\/p>\n
14<\/p>\n
15<\/p>\n
16<\/p>\n
17<\/p>\n
18<\/p>\n
19<\/p>\n
20<\/p>\n
21<\/p>\n
22<\/p>\n
23<\/p>\n
24<\/p>\n
25<\/p>\n
26<\/p>\n
27<\/p>\n
28<\/p>\n
29<\/p>\n
30<\/p>\n
31<\/p>\n
32<\/p>\n
33<\/p>\n
34<\/p>\n
35<\/p>\n
36<\/p>\n
37<\/p>\n
38<\/p>\n
39<\/p>\n
40<\/p>\n
41<\/p>\n
42<\/p>\n
43<\/p>\n
44<\/p>\n
45<\/p>\n
46<\/p>\n
47<\/p>\n
48<\/p>\n
49<\/p>\n
50<\/p>\n
51<\/p>\n
52<\/p>\n
53<\/p>\n
54<\/p>\n
55<\/p>\n
56<\/p>\n
57<\/p>\n
58<\/p>\n
59<\/p>\n
60<\/p>\n
61<\/p>\n
62<\/p>\n
63<\/p>\n
64<\/p>\n
65<\/p>\n
66<\/p>\n
67<\/p>\n
68<\/p>\n
69<\/p>\n
70<\/p>\n
71<\/p>\n
72<\/p>\n
73<\/p>\n
74<\/p>\n<\/div>\n
# notion.py<\/span><\/p>\n # Conditions: none past Python’s normal library<\/span><\/p>\n # Run: python notion.py<\/span><\/p>\n \u00a0<\/p>\n from <\/span>dataclasses <\/span>import <\/span>dataclass<\/span>,<\/span> <\/span>subject<\/span><\/p>\n from <\/span>typing <\/span>import <\/span>Any<\/span><\/p>\n from <\/span>enum<\/span> <\/span>import <\/span>Enum<\/span><\/p>\n import <\/span>json<\/span><\/p>\n from <\/span>datetime <\/span>import <\/span>datetime<\/span>,<\/span> <\/span>timezone<\/span><\/p>\n \u00a0<\/p>\n class<\/span> <\/span>InputSource<\/span>(<\/span>Enum<\/span>)<\/span>:<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>USER_TEXT<\/span> <\/span>=<\/span> <\/span>“user_text”<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>WEBHOOK<\/span> <\/span>=<\/span> <\/span>“webhook”<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>FILE_UPLOAD<\/span> <\/span>=<\/span> <\/span>“file_upload”<\/span><\/p>\n \u00a0<\/p>\n @<\/span>dataclass<\/span><\/p>\n class<\/span> <\/span>AgentInput<\/span>:<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>“”<\/span>“<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0The normalized inner form each downstream part consumes,<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0no matter the place the uncooked enter really got here from. That is the<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0complete level of a notion layer: all the pieces previous this level<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0solely ever sees this one construction.<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0“<\/span>“”<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>supply<\/span>:<\/span> <\/span>InputSource<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>content material<\/span>:<\/span> <\/span>str<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>metadata<\/span>:<\/span> <\/span>dict<\/span>[<\/span>str<\/span>,<\/span> <\/span>Any<\/span>]<\/span> <\/span>=<\/span> <\/span>subject<\/span>(<\/span>default_factory<\/span>=<\/span>dict<\/span>)<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>received_at<\/span>:<\/span> <\/span>str<\/span> <\/span>=<\/span> <\/span>subject<\/span>(<\/span>default_factory<\/span>=<\/span>lambda<\/span>:<\/span> <\/span>datetime<\/span>.<\/span>now<\/span>(<\/span>timezone<\/span>.<\/span>utc<\/span>)<\/span>.<\/span>isoformat<\/span>(<\/span>)<\/span>)<\/span><\/p>\n \u00a0<\/p>\n def <\/span>perceive_user_text<\/span>(<\/span>raw_text<\/span>:<\/span> <\/span>str<\/span>)<\/span> <\/span>-><\/span> <\/span>AgentInput<\/span>:<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>“”<\/span>“Uncooked chat enter — the best case, but it surely nonetheless wants normalization.”<\/span>“”<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>return<\/span> <\/span>AgentInput<\/span>(<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/span>supply<\/span>=<\/span>InputSource<\/span>.<\/span>USER_TEXT<\/span>,<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/span>content material<\/span>=<\/span>raw_text<\/span>.<\/span>strip<\/span>(<\/span>)<\/span>,<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<\/span>metadata<\/span>=<\/span>{<\/span>“channel”<\/span>:<\/span> <\/span>“chat”<\/span>}<\/span>,<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>)<\/span><\/p>\n \u00a0<\/p>\n def <\/span>perceive_webhook<\/span>(<\/span>raw_payload<\/span>:<\/span> <\/span>str<\/span>)<\/span> <\/span>-><\/span> <\/span>AgentInput<\/span>:<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>“”<\/span>“<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0A webhook delivers structured JSON, not plain textual content. Notion extracts<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0the half the agent ought to cause about and discards transport-level<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0noise like headers and signatures.<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0“<\/span>“”<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>payload<\/span> <\/span>=<\/span> <\/span>json<\/span>.<\/span>masses<\/span>(<\/span>raw_payload<\/span>)<\/span><\/p>\n \u00a0\u00a0\u00a0\u00a0<\/span>event_type<\/span>