Agent Blueprint

Agent Blueprint - Build Production-Grade AI Agents

Generate complete, working AI agents using battle-tested patterns studied from production-grade agentic systems. Every pattern is independently implemented and adapted for any framework, language, or purpose.

When to Use

Use this skill when:

• Building any kind of AI agent or agentic tool
• Creating a coding assistant, research agent, or task automation agent
• Designing an agent architecture with tools, permissions, and context management
• Scaffolding a new agent project from scratch
• Cloning or recreating Claude Code-like functionality
• Building multi-step automated workflows with planner + executor architecture
• Embedding an agent inside a web application via HTTP/SSE API
• Adding human-in-the-loop approval checkpoints to an autonomous agent
• Making an agent production-ready (observability, cost control, long tasks)

Do NOT use when:

• Building a simple chatbot without tools (use prompt engineering instead)
• Creating a non-agentic API wrapper (use your SDK directly)

The 5-Phase Build Process

Phase 1: Define Your Agent

Before writing any code, answer these 4 questions. Write answers to a AGENT.md spec file in your project:

1. PURPOSE: What does this agent do in one sentence?
2. TOOLS: What actions can it take? (file ops, shell, web, APIs, custom)
3. TRIGGERS: When should it act autonomously vs wait for input?
4. OUTPUT: What does "done" look like? (code changes, reports, files, etc.)

Based on your answers, choose a template:

For TypeScript/Bun: use references/typescript-agent-loop.md as your starting point and examples/typescript-research-agent.md as a runnable example. For Rust: use references/rust-agent.md.

Not sure which template? Use this quick selector:

Phase 2: Implement Core Components

Build these 5 components in order. Each is a separate module:

agent/
  core/
    agent_loop.py      # The main while-true loop (Phase 2.1)
    tool_registry.py   # Tool definitions and dispatch (Phase 2.2)
    permissions.py     # Allow/deny/ask permission system (Phase 2.3)
    context.py         # Message history and compaction (Phase 2.4)
    system_prompt.py   # Dynamic prompt assembly (Phase 2.5)

Phase 2.1: The Agent Loop

The heart of every agent. This is the while(true) pattern that drives all agentic behavior:

async def agent_loop(messages, tools, system_prompt, api_client):
    while True:
        # 1. Manage context window
        messages = compact_if_needed(messages)

        # 2. Call the LLM with streaming
        response = await api_client.stream(
            system=system_prompt,
            messages=messages,
            tools=tools.to_api_schema(),
        )

        # 3. Process response blocks
        assistant_content = []
        for block in response:
            if block.type == "text":
                assistant_content.append(block)
            elif block.type == "tool_use":
                # 4. Check permissions
                decision = permissions.check(block.name, block.input)
                if decision == "deny":
                    assistant_content.append(tool_error(block.id, "Permission denied"))
                    continue

                # 5. Execute tool
                result = await tools.execute(block.name, block.input)
                messages.append(tool_result(block.id, result))
                assistant_content.append(block)

        messages.append(assistant_message(assistant_content))

        # 6. Continue if tools were used, stop if text-only
        if not any(b.type == "tool_use" for b in assistant_content):
            break

    return messages

Critical patterns:

• Stream responses for real-time feedback
• Execute concurrency-safe tools in parallel
• Handle prompt_too_long errors by compacting context
• Track token usage and cost per turn

Load references/agent-loop.md for the complete loop with error recovery, streaming, and cost tracking.

Phase 2.2: The Tool System

Every tool implements this interface:

class Tool:
    name: str                    # Unique identifier (e.g., "bash", "read_file")
    description: str             # What it does (shown to LLM)
    input_schema: dict           # JSON Schema for parameters
    is_read_only: bool           # True if no side effects
    is_concurrency_safe: bool    # True if parallel execution is safe

    async def call(self, input: dict, context: dict) -> ToolResult:
        """Execute the tool and return result."""

    def check_permissions(self, input: dict) -> PermissionDecision:
        """Return allow/deny/ask for this specific invocation."""

    def validate_input(self, input: dict) -> ValidationResult:
        """Validate parameters before execution."""

Built-in tools to implement first:

Load references/tool-system.md for complete tool implementations with Zod/Pydantic schemas.

Phase 2.3: The Permission System

Defense-in-depth permission checking:

def check_permission(tool_name, tool_input, context):
    # Layer 1: Always-deny rules (hardcoded safety)
    if matches_deny_rule(tool_name, tool_input):
        return DENY

    # Layer 2: Tool-specific checks
    tool_check = tools[tool_name].check_permissions(tool_input)
    if tool_check in (ALLOW, DENY):
        return tool_check

    # Layer 3: Always-allow rules (user-configured patterns)
    if matches_allow_rule(tool_name, tool_input):
        return ALLOW

    # Layer 4: Safety checks for sensitive paths
    if is_sensitive_path(tool_input):
        return ASK

    # Layer 5: Ask the user
    return ASK

Permission rule format: "ToolName(pattern)" — e.g., "Bash(git *)", "Read", "Edit(*.ts)"

Load references/permission-system.md for the complete 7-layer permission pipeline.

Phase 2.4: Context Management

The #1 challenge in production agents. Implement these 3 strategies:

Strategy 1: Auto-Compact — When approaching context limits, summarize old messages:

if token_count(messages) > context_window - buffer:
    messages = await summarize_old_messages(messages, keep_recent=5)

Strategy 2: Tool Result Budget — Persist large outputs to disk, keep summaries in context:

if len(tool_result.content) > MAX_INLINE_SIZE:
    path = save_to_disk(tool_result.content)
    tool_result.content = f"[Result too large. Full output at: {path}]"

Strategy 3: Micro-Compact — Replace old tool results with [Old tool result cleared]:

for msg in messages[:-RECENT_WINDOW:]:
    if msg.type == "tool_result" and msg.age > TURNOVER_THRESHOLD:
        msg.content = "[Old tool result content cleared]"

Load references/context-management.md for the complete context lifecycle.

Phase 2.5: System Prompt Assembly

Build the system prompt as a string array, not a single blob:

def build_system_prompt(tools, context):
    parts = []

    # Static prefix (cacheable)
    parts.append(identity_section())        # "You are..."
    parts.append(tool_instructions(tools))  # Per-tool usage rules
    parts.append(output_rules())            # Formatting, verbosity

    # Dynamic boundary (changes per turn)
    parts.append(current_datetime())        # Timestamp
    parts.append(git_context(context))      # Branch, status
    parts.append(user_context(context))     # CLAUDE.md or project config

    return parts

Key pattern: Split static/dynamic content with a cache boundary. Static prefix gets cached by the API (10x cheaper). Dynamic suffix changes every turn.

Load references/system-prompts.md for the complete prompt template.

Phase 3: Add the Interaction Layer

Choose your UI:

Terminal UI component tree (React/Ink pattern):

App
  Messages          # Virtual scrollable message list
  Spinner            # "Thinking..." / "Running bash..." indicator
  PromptInput        # User input with history, autocomplete
  PermissionDialog   # "Allow Bash(git push)?" prompt
  CostDisplay        # Running token/cost counter

Phase 4: Add Advanced Features

These make a good agent into a great one:

Phase 5: Validate and Ship

Run the validation script to verify your agent has all critical components:

python scripts/validate_agent.py ./my-agent

This checks:

• Agent loop handles tool_use and text responses
• Tool registry with proper schemas
• Permission system with deny/allow/ask
• Context compaction for long conversations
• System prompt assembly
• Error handling for API failures
• Cost tracking

Templates

Ready-to-use starting points. Copy and customize:

Examples

Complete walkthroughs of real agent builds:

Scripts

Reference Files

Deep-dive documentation for each subsystem. Load when you need implementation details: