Why Build Your Own Agent: From Chat to Reliable Execution

01 | Global Perspective: Chatting Is Not Completing

The author opens by contrasting two common failure patterns. In the first, a demo shows fluent streaming chat, but the agent cannot modify configuration files, run scripts, or deliver artifacts — the environment remains unchanged. The misdiagnosis is often "model not smart enough" or "prompt needs tuning," but the root cause is that the chain stops at "text visible" without a container runtime, tool loop, workspace, or permission layer. In the second pattern, a local CLI demo works, but multi-user rollout reveals gateway failures, missing first tokens, permission popup storms, and tools that ignore stop signals. The misdiagnosis blames concurrency or infrastructure, while the real issue is missing layer boundaries: traffic gateway, agent gateway, resource pool, and runtime turn cancellation are conflated.

Core distinction: Chat solves "text visible"; an Agent system must solve "work done and auditable." The series rejects "launched" as a milestone and instead defines a four-stage ladder with minimum evidence for each stage.

02 | Industry Survey: What Gaps Each Approach Fills

A comparison evaluates five forms:

Pure Chat / Assistant Page (e.g., web chat UIs): Strengths — fast onboarding, good first-token feel. Weaknesses — almost no execution surface, hard to change environment.

Local IDE Agent (e.g., Cursor, Codebuddy, Cline): Strengths — strong code-editing experience, process is local. Weaknesses — multi-tenancy, IM, pooling are separate concerns.

Orchestration Frameworks (e.g., LangGraph, AutoGen, CrewAI): Strengths — graph/multi-agent control, many observability points. Weaknesses — still need to build host, egress, isolation yourself.

Cloud Consumer Agents (products with sandbox/tools): Strengths — strong "can do work" feel. Weaknesses — first response, cost, permissions are hard problems.

Self-built Layered Platform (this series) (Portal + Gateway + Pool + Runtime): Strengths — multi-entry, governable, auditable. Weaknesses — large engineering surface, must enforce layering.

What to borrow: From local IDE agents — tool loop + writable workspace UX standard; from orchestration frameworks — expressible state, branchable failure, cancellable turns; from cloud agents — isolation and quota awareness.

What to reject: Calling a Chat API wrapper an Agent; copying a full Agent per entry (browser, IM, CLI, IDE); using the model vendor name as the architecture diagram.

Conclusion: Public products prove "can chat" and "local can do work"; but for cloud multi-tenant, multi-entry, governed scenarios, self-built layering is unavoidable — not for show, but for boundaries.

03 | Design Conclusion: Capability Ladder Over Feature List

The series recognizes only four stages, each with a minimum evidence bar:

Can Chat — Path connected, first token streams, session handoff works. Minimum evidence: any one of web/IM/CLI streams response.

Can Do Work — Tools, workspace, permissions, artifacts. Minimum evidence: can modify environment, ask permissions cleanly, deliver files.

Runs Stably — Latency, pool, warm-up, egress, cancellation. Minimum evidence: no jitter at peak, clean stop, display doesn't glitch.

Reusable — Cost, observability, security, methodology. Minimum evidence: new business can diagram, hook gates, no tribal knowledge.

Because business wants results and stability, not which interface shipped this week, the series follows the ladder, not a feature checklist. Because "launched" lacks verifiable evidence, each stage requires a minimum evidence table — otherwise teams substitute slogans for delivery. Skipping stages creates a debt flywheel: demo chats → claim Agent done → business asks for work → bolt on tools → entry points multiply → peak jitter, fake stops → blame the model. The ladder also tells you when not to optimize: polishing IM bubble byte budgets during "Can Chat" is waste; promising sub-second first response without a resource pool is self-deception.

04 | Implementation Intuition: Speak in Layers

During self-build, the author forces layer-based reasoning instead of product names. Product names change; layers are relatively stable. Because symptoms lose context across teams, the first troubleshooting sentence must name the layer: is it the traffic entry, the agent path missing first token, or the capability egress rejecting a tool?

Two reference implementations (TypeScript and Python) map symptoms to candidate layers:

// TypeScript - agent-sdk 0.3.x concept alignment
type AgentLayer =
  | "ingress"              // Browser / IM / IDE / CLI
  | "edge_gateway"         // Traffic entry: site opens
  | "platform"             // Portal + BFF: identity, assets, session entry
  | "capability"           // OpenAPI / MCP / Token
  | "orchestrator"         // Release, resource pool, sandbox
  | "agent_path"           // Agent gateway → container runtime
  | "client_tool";        // CLI / IDE plugin

function blameFirst(symptom: string): AgentLayer[] {
  if (symptom.includes("site down") || symptom.includes("static 404")) {
    return ["edge_gateway", "platform"];
  }
  if (symptom.includes("no first token") || symptom.includes("dialogue timeout")) {
    return ["orchestrator", "agent_path"];
  }
  if (symptom.includes("tool permission") || symptom.includes("MCP")) {
    return ["capability", "agent_path"];
  }
  if (symptom.includes("machine not enough") || symptom.includes("pool empty")) {
    return ["orchestrator"];
  }
  if (symptom.includes("IM display") || symptom.includes("bubble")) {
    return ["platform"]; // egress projection, not model failure
  }
  return ["platform"];
}

# Python - host-runtime 1.x concept alignment
SYMPTOM_TO_LAYERS = {
    "site_down": ["edge_gateway", "platform"],
    "no_first_token": ["orchestrator", "agent_path"],
    "tool_denied": ["capability", "agent_path"],
    "im_display_broken": ["platform"],  # egress projection
    "stop_ignored": ["agent_path"],     # turn cancel didn't reach runtime
    "workspace_stale": ["orchestrator", "agent_path"],  # release/sync
}

def hypothesize(symptom: str) -> list[str]:
    return SYMPTOM_TO_LAYERS.get(symptom, ["platform"])

Failure boundaries: Layer tags are navigation, not verdicts — evidence may overturn. "IM display broken" defaults to projection layer first, but model side isn't forever innocent; wrong priority burns the golden hour. Client tools (CLI/IDE plugins) are first-class entries, not side toys; they must appear on the diagram.

05 | Because Multi-Entry, Kernel Must Be Hostable

Real platforms face at least browser, IM, IDE, CLI, external OpenAPI — and more will come (embedded SDK, bot callbacks, scheduled triggers). Because entry protocols differ (some have modals, some only bubbles, some only SSE), you cannot copy a full Agent per entry. Correct split:

One conversation/tool kernel (container runtime + SDK/CLI)

Multiple host policies (with/without UI, how to project events, how to degrade survey-type tools)

Invariant: "One kernel, forked host policies." TypeScript and Python snippets define HostKind and HostPolicy (canModal, projectEvents, degradeSurveyToText) for web, im, ide, cli, openapi. A present_permission function shows modal for web/ide, text survey for others.

// TypeScript
type HostKind = "web" | "im" | "ide" | "cli" | "openapi";

interface HostPolicy {
  canModal: boolean;         // 能否弹权限窗
  projectEvents: boolean;    // 是否负责 UI 投影
  degradeSurveyToText: boolean;
}

const HOST_POLICY: Record<HostKind, HostPolicy> = {
  web: { canModal: true, projectEvents: true, degradeSurveyToText: false },
  im: { canModal: false, projectEvents: true, degradeSurveyToText: true },
  ide: { canModal: true, projectEvents: true, degradeSurveyToText: false },
  cli: { canModal: false, projectEvents: false, degradeSurveyToText: true },
  openapi: { canModal: false, projectEvents: false, degradeSurveyToText: true },
};

# Python
def present_permission(host: str, question: str) -> str:
    if host in ("web", "ide"):
        return f"modal:{question}"
    # IM / CLI / OpenAPI：无弹窗，只能文本协议
    return f"text_survey:{question}"

Failure boundaries: Host policies may fork; capability table (which tools, workspace writable) must not fork — forking doubles debugging cost forever. Degradation ≠ castration: IM lacks modal, but permission must still be asked, just via text. OpenAPI/CLI must converge into the same agent path, not spawn a "sidecar Agent."

06 | Full Lifecycle: How to Read This Series

Suggested reading order with decision points:

Opening (this post) → Set the ladder. Decision: Do you need web QA only, or env mutation + multi-entry? Former: don't self-build; latter: continue.

One Diagram to Understand Layering → Draw skeleton. Decision: Are traffic gateway and agent gateway drawn separately? Merged box guarantees layer confusion later.

Model / Runtime / Host → Disambiguate terms. Decision: When things break, blame model first or ask "where is execution face, where is projection?"

Life of a Conversation → Be able to narrate the path. Decision: Can the minimal chat path trace from portal/BFF to container runtime? If not, you haven't even reached "Can Chat."

Tool & MCP → Where capabilities come from. Decision: Are tool config and token/auth at capability egress, not relying on model "good behavior"?

Container Runtime → Execution face stands firm. Decision: Are process/connection/turn accounted separately? Pinging port only is self-deception.

Then "Runs Stably" : first response, pool level, warm-up merge, IM projection, dual host, IDE plugin. Decision: Each post tackles one hard problem; don't parallel "optimize everything a little."

Closure: Cost auth → Security deep-dive → Observability & evolution → Playbook. Decision: When switching business, can you leave with just one layer diagram + one gate checklist? If not, not reusable yet.

If time-pressed: read "Layer Diagram + Container Runtime + First Response" for ~80% engineering intuition; rest by symptom. Reading path can skip; ladder cannot — no "Can Do Work" but talking "Runs Stably" only stacks dashboards.

07 | Industry Comparison / Selection Matrix: To Build or Not

Comparison across five dimensions:

Multi-entry (Web/IM/CLI) : Chat API only — weak; Buy IDE Agent — IDE-biased; Orchestration + Thin Shell — medium (self-host); Self-built Layered Platform — strong (must build).

Cloud multi-tenant & pooling : Chat API only — none; Buy IDE Agent — weak; Orchestration + Thin Shell — weak; Self-built Layered Platform — strong (hard problem).

Tool / MCP governance : Chat API only — weak; Buy IDE Agent — medium; Orchestration + Thin Shell — medium; Self-built Layered Platform — strong (unifiable).

First response & cost control : Chat API only — vendor-dependent; Buy IDE Agent — local feel good; Orchestration + Thin Shell — depends on wiring; Self-built Layered Platform — must build budget.

Methodology portability : Chat API only — low; Buy IDE Agent — medium; Orchestration + Thin Shell — medium-high; Self-built Layered Platform — high (series goal).

Choose Chat API only when: Only web QA, no execution face, no multi-tenant — don't self-build for vanity. Choose IDE Agent when: Team mainly edits code locally, cloud governance not your problem. Choose Orchestration + Thin Shell when: You need graph/multi-agent control and are willing to build host and egress yourself. Choose Self-built Layered when: Need env mutation, IM/CLI, quotas and audit — then "build your own Agent" is not sentiment, it's responsibility boundary.

Behind the matrix: "Self-build value is boundaries and portable methodology, not another chat wrapper. Wrapping chat anyone can do; layering and reconciliation are your moat — and your debt."

08 | Common Pitfalls

Pitfall 1: Substituting "Launched" for Ladder

Trigger: Review only wants green light; weekly report must say "completed"; demo only tests chat path. Wrong fix: Add more features, swap larger model, treat demo recording as acceptance. Right fix: Every review asks: now at Can Chat, Can Do Work, or Runs Stably? Check against minimum evidence table; no check, no redefinition.

Pitfall 2: Architecture by Weekly Report Features

Trigger: Org splits tasks by interface/page; architecture diagram follows task list. Wrong fix: Draw denser service catalog; fill boxes with product names. Right fix: Pin layer diagram first, map features to layers; features that don't fit wait — usually means boundaries unclear.

Pitfall 3: Copy Agent Per New Entry

Trigger: IM protocol special, CLI needs speed, IDE needs plugin — each entry team wants "own control." Wrong fix: Fork tool loop / permission logic / workspace rules per entry. Right fix: One kernel, forked host policies; capability table stays unified. Capability fork is debt, not flexibility.

Pitfall 4: Treating Model Vendor as Architecture

Trigger: Procurement contracts, eval leaderboards, external narrative all love model names. Wrong fix: Architecture diagram centers a giant model logo, scattered "plugins" around. Right fix: Model is swappable; traffic gateway, agent gateway, resource pool, container runtime, projection layer are your system. Swapping model must not equal swapping architecture.

Summary

Chat is "text visible"; Agent system is "work done and governable."

This series climbs Can Chat → Can Do Work → Runs Stably → Reusable, not by interface checklist.

Multi-entry forces hostable kernel, not copied Agents.

Troubleshooting and design both speak in layers; ban product-name-only talk.

Self-build value is boundaries and portable methodology, not another chat wrapper.

Public products lend UX and graph orchestration; cloud multi-tenant governance bill is yours to own.

Next post: One Diagram to Understand Self-built Agent Layering — turning entries, gateways, platform, orchestration, runtime into a photocopyable sketch.