Postman Agent Mode Architecture Explained: How 170+ Tools Shrink to 15

Postman's Agent Mode runs on Amazon Bedrock, but the engineering details that are truly worth paying attention to are not the model itself, but the entire system built around the model. Postman and AWS jointly disclosed three interconnected design decisions: narrowing the visible tool set for each task, preparing context through dedicated paths, and retaining human approval in the execution flow. Together, these decisions form a reusable Agent architecture paradigm.

Tool Selection: From 170+ to About 15 Task Tools

In testing, Postman found that once the visible tool set exceeds about 40, the tool selection error rate begins to climb. This observation directly led to the task-based retrieval mechanism. Agent Mode no longer exposes the full catalog of 170+ tools to the model. Instead, it first searches for relevant capabilities, narrows the set to about 15, and then hands them to a context-isolated sub-agent for execution.

The retrieval step therefore becomes critical—it determines which capabilities the executing Agent can obtain. This design shifts the cognitive burden of tool selection from the model to the retrieval system while reducing the risk of tool misuse. For structured data, Postman also introduced schema-aware read-only access to ClickHouse tables, allowing direct queries of structured information instead of building a narrow-purpose tool for each question.

Task-based retrieval is a technique that dynamically narrows the set of tools visible to the model at runtime. Its core idea is: rather than exposing all available tools to the model at once, first retrieve the most relevant subset from the tool catalog based on the current task description (about 15 in Postman's practice), and then hand that subset to the executing Agent.

This approach contrasts with traditional "full tool registration." The advantage of full registration is that the model can always see all capabilities, but the cost is that the selection space is too large, which easily triggers misselection or hallucinated calls. Task-based retrieval moves the decision of "which tools to choose" from model reasoning to the retrieval system, which can rank based on signals such as semantic similarity, tool descriptions, and historical usage patterns.

It is worth noting that retrieval quality directly determines the capability boundary of the executing Agent: if retrieval misses a tool that is truly needed, the execution stage cannot remedy it. Therefore, the retrieval system itself also needs observability and evaluation mechanisms, not just model-side performance metrics.

Two Paths for Context Preparation

Postman regards missing or incomplete context as a major bottleneck. To address this, Agent Mode designed two context acquisition paths: background context is automatically collected from the workspace and pruned before entering the prompt; focused context comes from user selections or mentions and is delivered through handlers customized for the relevant Postman objects.

This design involves a clear trade-off: pruned context limits the amount of information reaching the model, so having workspace access does not mean every relevant detail will survive the prompt preparation stage. Postman chooses to accept this limitation in exchange for more controllable input quality.

Context pruning refers to actively filtering, summarizing, or truncating collected information before sending it into the prompt, in order to control the number of input tokens and the signal-to-noise ratio. Postman's background context path adopts this mechanism: not all information automatically collected from the workspace is retained; it is pruned before entering the prompt.

The benefit of pruning is reducing the probability that the model is distracted by irrelevant information, as well as lowering token costs and latency; the cost is information loss—some details judged irrelevant during pruning may later prove critical in subsequent reasoning. This trade-off is especially prominent in long-context scenarios: the larger the model window, the more raw information can theoretically be stuffed in, but the reasoning quality loss caused by a lower signal-to-noise ratio often exceeds the gain from increased information volume.

Therefore, context pruning strategies need to match the task type: for structured query tasks, pruning can be more aggressive; for complex tasks requiring cross-object associations, more complete context should be retained, or supplemented on demand through multi-round retrieval.

Inference Routing, Caching, and Data Redaction

Agent Mode accesses Claude models through Bedrock's inference API and routes workloads using cross-region inference profiles. Prompt caching uses a dual-checkpoint strategy: a one-hour checkpoint for stable content and a five-minute checkpoint for variable context. It should be noted that cache support is model-dependent and not universally guaranteed.

On privacy, Postman uses Bedrock Guardrails to redact PII before data reaches the model, and enterprise administrators can configure related policies. This layer complements human approval: redaction handles the information passed to the model, while approval controls the changes made through the application.

Prompt caching is an optimization mechanism that reuses already-processed prefixes at the model inference layer. When multiple requests share the same prefix content (such as system prompts, tool definitions, and stable background knowledge), caching avoids recomputing the attention states of these tokens, thereby reducing latency and cost.

Postman adopts a dual-checkpoint strategy: a longer cache validity period (one hour) for stable content and a shorter validity period (five minutes) for variable context. The logic of this layered design is that stable content is reused frequently and changes little, so a long validity period amortizes the cost of establishing the cache; variable context changes frequently, so a short validity period avoids the extra overhead caused by cache invalidation.

It should be noted that cache support varies by model and API, and not all models guarantee cache hits. In engineering terms, caching should be treated as a performance optimization rather than a correctness dependency, and functionality should degrade gracefully when the cache misses.

Approval Mechanism Always in the Loop

Agent Mode requires user approval for operations that modify application state, and background request sending is no exception. This means that even if some operations are executed asynchronously in the background, as long as they involve state changes, human confirmation remains a necessary step. This design embeds human judgment at key nodes in the execution flow, rather than serving only as an after-the-fact audit measure.

Human-in-the-loop approval in Agent architecture usually refers to inserting human confirmation steps at key nodes in the execution flow, rather than merely recording operations in an after-the-fact audit log. Postman's design requires all operations that modify application state to undergo user approval, including background asynchronous requests.

This is fundamentally different from the "post-hoc audit" model: post-hoc auditing can only discover problems and cannot prevent erroneous operations from taking effect; human-in-the-loop approval intercepts operations before they take effect, embedding human judgment into the execution path. The cost is reduced automation—approval waiting introduces latency and may become a bottleneck in high-frequency operation scenarios.

Therefore, the design of approval granularity is crucial: overly coarse approval (such as one confirmation for the entire task) weakens control, while overly fine approval (such as one confirmation for each tool call) overwhelms users. Postman chooses "state change" as the boundary, striking a balance between control and usability.

Architectural Insights and Open Questions

This case study is better read as an architecture walkthrough—it documents how Postman scopes tools, prepares context, routes inference, and retains human control. However, the study does not provide measured task success rate data, nor does it include an independent security assessment.

One detail that needs clarification is that the widely circulated "40 million developers" refers to Postman's developer community, not the number of Agent Mode users. For teams building enterprise-grade Agents, Postman's practice provides a reference template: use retrieval to narrow the tool set, use dual paths to manage context, and use layered mechanisms to balance automation and human control.

This article is based on the full analysis by Agentic Affairs; more source references and architecture diagrams can be found in the original article.

One-line Summary

Postman Agent Mode uses retrieval to narrow the tool set, dual paths to manage context, and human-in-the-loop approval to build a reusable Agent architecture.

Paragraph Summary

Postman and AWS disclosed three core design decisions for Agent Mode running on Amazon Bedrock: first, task-based retrieval narrows 170+ tools to about 15, because the selection error rate rises when the tool set exceeds about 40; second, context preparation has two paths—automatic background collection with pruning, and focused context through object-customized handlers; third, all operations that modify application state require user approval, including background requests. The inference layer uses Bedrock cross-region inference profiles for routing, prompt caching adopts a dual-checkpoint strategy of one hour and five minutes, and Bedrock Guardrails redact PII before model calls. The case does not provide task success rates or an independent security assessment, and "40 million developers" refers to community size rather than the number of Agent Mode users.