How does the agent system work?

How does the agent system work in this codebase?

Perfect! Now I have a comprehensive understanding. Let me create a summary document:

##How the Agent System Works

The agent system in this codebase is a sophisticated multi-layered architecture that enables AI agents to answer questions about and build features in GitHub repositories. Here's how it works:

###Core Architecture

The agent system consists of several key components:

####1. Agent Types (apps/web/agent/types.ts)

• AgentMode: Two modes of operation:
  • "ask": Agent analyzes the repo and answers questions with read-only access
  • "build": Agent can make modifications and create PRs (write access)
• AgentUIMessage: Messages in the chat with optional error codes and mode metadata

####2. Response Agent (apps/web/agent/response-agent.ts)

This is the main orchestrator that:

1. Setup Phase (setupStep):

   • Loads the post and all previous comments from the forum
   • Resolves the git reference (branch/tag/commit SHA)
   • Creates a workspace in a Vercel Sandbox (read-only for "ask" mode, writable for "build" mode)
   • Stores git context data (SHA, branch, tags, message, date) for the post

2. Streaming Loop (streamTextStep):

   • Starts workspace setup in the background (non-blocking)
   • Enters a loop that can run up to 100 steps
   • Each step:
     • Passes the conversation history and available tools to the AI model (Claude)
     • Streams the model's response back to the client
     • Continues until the model signals it's done (finishReason === "stop")
   • Tracks token usage and costs

3. Closing Phase (closeStreamStep):

   • Saves the complete conversation to the database
   • Updates posts with git context and metadata
   • Logs the billing costs for the interaction

####3. Workspace System (apps/web/agent/workspace.ts)

Creates isolated execution environments:

• Shared Sandboxes: One per repository (reused across questions) for "ask" mode
• Build Sandboxes: One per forum post in "build" mode (temporary, tied to a specific task)
• LazyWorkspace: Optimized pattern that:
  • Returns immediately with the sandbox ID and resolved SHA
  • Clones the repo in the background without blocking the agent
  • Tools internally wait for setup via bash polling (so waits happen inside the sandbox, not in Node)
• Two Clone Strategies:
  • Shallow Clone (ask mode): Fast clones just one specific commit
  • Full Clone (build mode): Needed for git operations and creating PRs

####4. Tools System (apps/web/agent/tools/index.ts and build-tools.ts)

Ask Mode Tools (read-only):

• Read: Read files with line-range support
• Grep: Search code using ripgrep
• List: Explore directory structure
• Bash: Run read-only shell commands
• RemoteBash: Execute commands in other GitHub repos
• WebSearch & WebExtract: Search and extract web content

Build Mode Tools (includes write access):

• Write: Create new files
• Edit: Make targeted replacements in files
• Delete: Remove files
• All read tools + additional git/PR capabilities
• Pre-configured git identity and credential handling

####5. Category Agent (apps/web/agent/category-agent.ts)

A specialized lightweight agent that:

• Generates a post title based on the content
• Assigns or creates a category (with emoji)
• Uses the fast Claude Haiku model
• Runs automatically when a post is created

###System Prompts

The agent receives context-appropriate system prompts:

Ask Mode:

• Told the repo is already cloned
• Instructed to ground answers in source code
• Encouraged to explore freely but not eagerly

Build Mode:

• Full write access to sandbox at /vercel/sandbox/{repo}
• Critical requirement: Must create a feature branch, make changes, commit, and push a PR
• Git is pre-configured with the authenticated user's identity
• Emphasized that without a PR, changes are lost when the sandbox ends

###Data Flow

1. User posts a question → Creates a forum post/comment
2. responseAgent is triggered via the start() workflow API
3. Workspace is created in background
4. AI model streams responses while using tools
5. Tools run commands in the sandbox, waiting for workspace setup if needed
6. Complete conversation is saved to database
7. Billing is charged based on token usage

###Key Design Patterns

• Lazy Initialization: Workspace setup happens in parallel with agent reasoning, not sequentially
• Streaming: Results stream to clients in real-time via WebSocket
• Sandbox Reuse: Sandboxes are cached and reused across multiple interactions
• TTL Management: Sandboxes have 10-minute timeouts that extend on reuse
• Workflow Integration: Uses Vercel's Workflow API for reliability and state persistence

This architecture enables the system to efficiently handle user interactions at scale while maintaining isolation, security, and cost control.