Prebuilt Agents

Potpie ships with three prebuilt agents that operate on the same underlying knowledge graph. Each is optimized for a different task pattern.

Ask

Understand your codebase. Ask answers questions about how something works, where something lives, what something does, and why it was built a certain way.

How it navigates

Before generating a response, Ask classifies the question by type — what, how, where, or why. Complex questions are broken into components and addressed sequentially.

Beyond the knowledge graph, Ask can:

• Read files directly by path (with optional line ranges)
• Read multiple files simultaneously for broad context
• Search file contents by pattern to pinpoint usage sites and definitions

When a question involves a third-party library, Ask retrieves external documentation via web search.

How it responds

Answers are structured with headers, code snippets, and citations to exact file locations. File paths are shown relative to the repository root.

---

Build

Make changes to your codebase. Build reads existing patterns and conventions from the knowledge graph before writing code, then generates code that matches the style and structure of your project.

Workflow

1. Describe — enter a description of the feature to build
2. Clarify — Potpie surfaces multiple-choice questions to lock in scope
3. Specify — a specification is generated covering files to create/modify, implementation details, and dependency relationships
4. Plan — a structured plan with summary, architecture diagram, and ordered tasks
5. Generate — code is produced and presented as diffs matching your existing style
6. Ship — create a PR directly from the generated changes

---

Debug

Trace issues to their root cause. Debug traverses the knowledge graph across affected components to find the true origin of a problem, not just where it surfaces.

Eight-step methodology

1. Understand and validate — confirms reported behavior against the codebase
2. Explore and hypothesize — traverses relevant code paths, generates candidate explanations
3. Identify root cause — pins failure to a specific file and line
4. Generalize — checks whether the same defect pattern appears elsewhere
5. Design solution — generates a fix scoped to the root cause
6. Scrutinize and refine — evaluates against edge cases and side effects
7. Implement — produces corrected code with exact file paths
8. Verify — validates fix against original failure and checks for regressions

What it returns

• Root cause traced to its true origin
• Mapped path from origin to symptom
• A fix that resolves the underlying issue, not just the specific reported instance

---

Spec Agent

The Spec Agent analyzes your repository before asking questions. It discovers your stack, architecture, and patterns, then asks clarifying questions grounded in those findings.

How it works

1. Explore — reads the repository, builds file tree, discovers framework and patterns
2. Clarify — generates 3–5 multiple-choice questions derived from actual codebase findings
3. Generate — produces a full specification including:
   • Executive summary
   • Success metrics
   • Functional and non-functional requirements
   • Architecture (with Mermaid diagram)
   • Technical design (data models, interfaces, API endpoints)
   • Open questions

Refinement

If a prior spec exists in the conversation, the agent applies only the requested modification and preserves all unchanged sections.

---

Using agents via API

All prebuilt agents are accessible through the API:

curl -X POST http://localhost:8001/api/v2/conversations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_ids": ["proj_abc123"],
    "agent_ids": ["spec_generation_agent"]
  }'

Then send messages to the conversation:

curl -X POST http://localhost:8001/api/v2/conversations/conv_xyz789/message/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Add a notifications system that supports email and in-app alerts"
  }'