Observation Normalisation
Normalise observations from heterogeneous tools into a uniform shape the agent can reason over without tool-specific logic.
This page is the complete instruction page for one pattern called "Observation Normalisation." It explains the problem this pattern solves, the idea behind the solution, when you should (and should not) use it, and what happens afterward, both the good effects and the costs.
This matters because building AI agents is not just about making them clever. It is also about making them safe and predictable. Following a well-tested pattern like this one helps avoid common mistakes, and shows you exactly which safety rules and regulations it connects to, listed under "Standards Mesh" on this page.
Context
Real agent toolsets mix REST APIs, SQL queries, search engines, file systems, and other agents. Each returns data in its own shape. Without normalisation, the reasoning prompt accumulates tool-specific handling.
Problem
Per-tool handling in the reasoning layer blocks substitution, inflates prompt size, and couples the agent to vendors.
Forces
- Tool idiosyncrasy vs agent portability
- Lossy normalisation vs fidelity
Solution
Adopt a uniform observation envelope: { tool, status, data, metadata, error, cost }. Adapt per-tool responses at the edge. The agent reasons over envelopes, not raw responses.
Where this pattern acts in the two lifecycles
05 Observe. Tool result ingestion, state update. 7 of 61 catalogue patterns act at this stage.
05 Operate & Monitor. Runtime telemetry, drift detection. 18 of 61 catalogue patterns act at this stage.
Stages and counts from the catalogue data. The Runtime lens is the loop the agent runs each turn; the AgentOps lens is the lifecycle the team runs the agent through. See the Matrix for every pattern at each stage.
Applicability
- Multi-tool agents
- Platform agents supporting pluggable toolsets
- Long-lived production agents
Anti-Patterns
- Tool-specific parsing in the agent prompt
- Copying raw responses into reasoning context
Consequences
- +Portability across tool providers
- +Smaller, more consistent reasoning context
- −Envelope design up-front cost
