1. “Subagents” — SubGraph / LangGraph team
| Point you captured | What it really means | Why it matters / best-practice |
|---|---|---|
| Avoid context poisoning with subagents | A subagent is a self-contained graph (a subgraph in LangGraph) that owns its own prompt prefix, memory, and tool list. Keeping those boundaries tight prevents stray instructions or tool descriptions from one part of an application from leaking into another, the classic “context poisoning” vector. | Think of each subagent as a micro-service for cognition. If an attacker (or just noisy upstream data) slips malicious instructions into one agent’s context window, the rest of the system is insulated. |
| Great for test-failure analysis, grep-style search, etc. | Subagents shine when the task can be split into specialists: e.g., a Failure-Classifier agent that reads CI logs, a File-Finder agent that uses ripgrep to surface candidate files, and a Patch-Writer agent that drafts a fix. | Each specialist gets the minimal tools it needs (CLI wrappers, search APIs) and returns a typed payload to the orchestrator. This keeps prompts small and tool calls predictable. |
| Orchestration is tricky | Orchestration in LangGraph usually follows one of two patterns: • Supervisor pattern – a top-level agent decides which child to invoke next based on a shared state object. • State-machine pattern – edges in the graph encode deterministic routing rules. Key pitfalls: circular dispatch loops, token bloat when the supervisor echoes every child’s output back into its own context, and race conditions when two subagents try to update shared state. | Use typed state objects and edge guards (boolean predicates) to keep control-flow explicit. LangGraph’s Timeout and MaxIterations nodes are your friends when an agent goes haywire |
Deep-dive ① — Subagents & Subgraphs • When to carve a subgraph: repeated logic, domain isolation, or separate ownership by different teams. • Tool-surface hygiene: expose only the UNIX commands or HTTP endpoints the subagent truly needs.
2. “To Build a Better Web” — Netlify
| Theme | Expansion |
|---|---|
| AX vs UX vs DX | UX is human end-users, DX is builders. AX (Agent Experience) is the third pillar: the affordances your platform gives autonomous LLM agents. If a deploy API requires auth headers that the agent can’t mint, the AX is broken even if DX is great. Netlify now treats AX as a first-class product metric. |
| Differentiation | • Products compete on UX (think aesthetics, speed). • Platforms compete on DX (SDKs, docs). • Infra and emerging agentic runtimes will compete on AX (stable tool schemas, low-latency context fetches). |
| Agentic primitives | Netlify’s “primitives” bundle: deploy.create, edgeFunction.invoke, asset.store. Each has a tersely-documented JSON schema, sized to fit easily inside a model context window (<1 KB). |
| MCP wrapper antipattern | Treating MCP as a thin “REST wrapper” over an existing API means your tool descriptions repeat every parameter; the prompt blows up and the agent gets confused. Netlify argues the MCP endpoint is the UI for the LLM—design it so a language model can reason about it, not a human. |
Deep-dive ② — Designing for AX • Keep each MCP tool ≤50 lines of JSON schema. • Offer progressive disclosure: a
plan.createtool that returns a follow-up link the agent can pass toplan.executekeeps individual calls small. • Return typed errors so the agent can branch (e.g.,{"error":"RATE_LIMIT","retry_after":30}).
3. “Designing an MCP Server” — WorkOS
| Bullet | Details & Implementation Hints |
|---|---|
| “Invest heavily in your tool description” | The tool description is the prompt. A well-named method (user.invite) plus JSON schema examples often out-perform paragraphs of natural-language docs. |
| Summary-doc as first tool | WorkOS’s MCP manifest puts a doc.summary tool in position 0. Every session calls it first, giving the agent a tight bullet-list of what the server can do, saving tokens. |
| ContextFetching (Playwright) | The open-source Playwright MCP server streams the page’s accessibility tree and lets the agent query CSS selectors directly. Great for context hydration—click a button, scrape the DOM, pass trimmed HTML back into the LLM. |
| API vs CLI wrappers | Wrapping a CLI (e.g., git, kubectl) avoids re-implementing complex flag logic. The server shells out, captures stdout, and returns it as structured JSON. |
| Elicitation | New MCP primitive where the server pauses execution and asks the client for structured input (schema-validated). Prevents gigantic “just in case” prompts. Think: “Which subscription should I cancel?” The agent issues an elicitation/create; UI collects the choice; the flow resumes. |
| Permission-gated tools | Attach RBAC scopes to tools so an agent running under a low-privilege token never even sees admin-only tools—keeps the context window lean and thwarts prompt-injection attacks that try to trick the agent into using them. |
| MCP UI & DOM streaming | WorkOS demoed piping live DOM nodes (similar to React’s server components) straight into the model’s context so it can reference #login-form > input[type="email"] without guessing. |
Deep-dive ③ — Elicitation Patterns
- Boolean confirmation: irreversible operations (
project.delete).- Disambiguation: multiple resources match (“Cancel which plan?”).
- Progressive form-fill: wizard-style flows.
- Security step-up: MFA challenges mid-session.
Cross-cutting Lessons
| Risk / Challenge | Mitigation |
|---|---|
| Context poisoning / tool-description attacks | • Isolate sub-agents. • Enforce signed tool manifests. • Strip or compress upstream content before insertion. |
| Token bloat | • Use subgraphs + scratch-pads. • Summarise long outputs before hand-off. • Rely on elicitation instead of pre-loading every possible variable. |
| Race conditions in orchestration | • Single-writer pattern: only one agent at a time may mutate shared state. • Deterministic edge guards. |
| DX vs AX trade-offs | Every extra enum value or optional param is more to explain in the tool schema. Simplify for the agent even if that means two separate tools for humans. |
Quick Reference (glossary)
- Subagent / Subgraph: Modular agent encapsulating its own prompt + tools.
- Supervisor: Top-level orchestrator node that routes tasks to subagents.
- AX: Agent Experience—how easily autonomous agents can use your platform.
- MCP: Model Context Protocol—JSON-RPC–style spec for tool calls.
- Elicitation: MCP primitive to request runtime user input via a typed schema.
- Context poisoning: Injecting malicious or distracting text into the model’s context window.
Linked Map of Contexts