Skip to content

Instantly share code, notes, and snippets.

@aaron-peloquin
aaron-peloquin / AX-prefer-concrete.md
Last active August 18, 2026 02:57
AX: Prefer Concrete (Code First, Model Second)

AX: Prefer Concrete (Code First, Model Second)

In software development, we never rely on conversational guesswork when a deterministic utility exists. We build CI pipelines that run automated test suites, validate strict schemas, and filter logs before browsing them with zero tokens spent.

Yet in GenAI engineering, we can routinely over-delegate to the model without thinking: asking an LLM to self-reflect, calculate values for us, or check for specific strings in the code and make a todo list of items to clean up.

Caution

Self-Reflection can Compounds Hallucinations: Asking an LLM to verify its own logic invites confirmation bias into the loop. Once a model hallucinates, subsequent conversational checks often rationalize the original error instead of catching it.

Only pay the model for reasoning, don't pay it to act like an nondeterministic (unpredictable) version of a script we could've ran instead.

@aaron-peloquin
aaron-peloquin / ax-analytics.md
Last active August 6, 2026 00:15
AX Analytics: Observing Agentic Behavioral Flows

AX Analytics: Track Agent actions like user events

Tracing tells us what executed; analytics tells us how an agent navigated. OpenTelemetry (OTel) traces and system logs capture individual API latencies and server errors, but they miss macro-level behavioral patterns across autonomous sessions.

Tools are a critical part of an agent's user interface and orchestration harnesses act as application routers, then we must analyze agent behavior with the same depth, visual intuition, and conversion rigor that we apply to human product analytics.

I built a prototype for this type of analytics platform.

Human UX Analytic Concept Agent Experience (AX) Equivalent
@aaron-peloquin
aaron-peloquin / ax-interface-routing.md
Last active July 13, 2026 23:36
Routing: Progressive Disclosure and SubAgent Delegation

Progressive AX and SubAgent Delegation

Loading dozens of tools into an Agent's context window upfront degrades system performance. It induces cognitive load, causes choice paralysis, increases parameter hallucinations, and wastes tokens.

Progressive AX and SubAgent Delegation are the two primary structural patterns for managing complex toolsets without overloading context.

Progressive AX vs. SubAgents: Choosing Your Work Boundary

Pattern Operational Metaphor Best Used When... Context Window Impact Risks
@aaron-peloquin
aaron-peloquin / ax-context-guidance.md
Last active July 10, 2026 01:01
AX: Context Markdown (SKILL) documents as Interface (Page) Copy

AX: Context documents as Interface (Page) Copy

When building Agentic systems, giving your Agent an MCP server full of tools is only half the battle. Tools act as the functional buttons and form inputs of your application. But an interface made entirely of empty input fields and naked buttons without text labels is impossible to navigate.

To bridge the gap between having a capability and knowing how to apply it, we use Context Markdown Documents (SKILLs) within the Agent's Harness. In Agent Experience (AX), these markdown documents act like our interface page copy, tooltips, and onboarding manuals.

Note

While Anthropic’s open-source SKILLs framework is the most popular structure for this pattern, the underlying concepts are universal. They map directly to Google Labs' DESIGN.md specification for UI coding agents, as well as ecosystem standards like .cursorrules or AGENTS.md files used to ground cod

@aaron-peloquin
aaron-peloquin / ax-mcp-guidance.md
Last active July 11, 2026 21:55
Agent Experience: MCP Servers

AX: Structuring MCP Servers as distinct Action Buttons

When building Agentic systems, our goal is to give our Agents the capabilities they need to be highly effective. A natural instinct is to provide an Agent with a comprehensive, all-in-one toolkit. However, presenting an Agent with too many tools at once introduces unnecessary "cognitive load" to them. When an Agent has to navigate a large, complex list of tools for a simple task, it impacts tool-selection accuracy, increases the chance of hallucinated parameters, and consumes valuable tokens and context window space on schemas irrelevant to that Agent's goal.

For decades, we've prioritized User Experience (UX)-structuring visual layouts to reduce friction for humans. In the era of GenAI, we must design for Agent Experience (AX).

Note

Just as a cluttered UI confuses a human user, a cluttered toolset confuses an Agent. To build precise, reliable systems, we lean on the Single Capability Principle: grouping tools into discrete, modula

AI Fundamentals: Intro to Agent Experience Design (AX)

As we transition from building traditional software integrations to engineering Agentic AI Systems, the way we design interfaces must fundamentally change - but I believe the patterns & principals we've developed over the years will stay.

We need to start thinking of our AI Agents as digital team members. Collaborators who communicate entirely through text and possess the unique ability to "say" JSON payloads to take real-world actions in their environment.

For the past 20 years on the web, our core focus as developers has been to craft a great User Experience (UX) - designing visual workflows, APIs, and frontends to reduce cognitive friction for human eyes and fingers. Today, we must shift our focus to Agent Experience (AX): building systems that make it effortless for GenAI Agents to reason accurately and successfully complete the tasks we give them.

What is Agent Experience (AX)?