New Agent

Step-by-Step Guide

1. Create Directory Structure

mkdir -p internal/agent/<agentname>

2. Create Agent File

Use this template based on internal/agent/income/income.go:

package <agentname>

import (
    "context"
    "encoding/json"
    "fmt"
    "strings"
    "time"

    "github.com/nimag/fast/internal/agent"
    "github.com/nimag/fast/internal/gemini"
    "github.com/nimag/fast/internal/guidelines"
    "github.com/nimag/fast/internal/model"
)

type Agent struct {
    gemini     *gemini.Client
    guidelines string
}

type Config struct {
    GuidelinesPath string
}

func New(geminiClient *gemini.Client) *Agent {
    return &Agent{gemini: geminiClient}
}

func NewWithConfig(geminiClient *gemini.Client, cfg Config) *Agent {
    a := &Agent{gemini: geminiClient}

    if cfg.GuidelinesPath != "" {
        loader := guidelines.NewLoader(cfg.GuidelinesPath)
        // Load appropriate section: "assets", "credit", or "collateral"
        if content, err := loader.LoadSection("<section>"); err == nil {
            a.guidelines = content
        }
    }
    return a
}

func (a *Agent) Type() agent.AgentType {
    return agent.AgentType<Name>
}

func (a *Agent) Name() string {
    return "<Name> Verification Agent"
}

func (a *Agent) RequiredDocuments() []model.DocumentType {
    return []model.DocumentType{
        // Add required document types
    }
}

func (a *Agent) OptionalDocuments() []model.DocumentType {
    return []model.DocumentType{
        // Add optional document types
    }
}

func (a *Agent) Dependencies() []agent.AgentType {
    return nil // Or list dependent agents
}

func (a *Agent) CanProceed(docs []*model.Document) (bool, []model.DocumentType) {
    required := a.RequiredDocuments()
    // Check if required docs are present
    // Return (true, nil) if can proceed
    // Return (false, missingTypes) if cannot
}

func (a *Agent) Analyze(ctx context.Context, input *agent.AnalysisInput) (*model.AnalysisResult, error) {
    // 1. Filter documents for this agent
    // 2. Build prompts
    // 3. Call Gemini
    // 4. Parse response
    // 5. Return AnalysisResult
}

3. Document Types by Agent

Assets Agent:

Required: DocTypeBankStatement
Optional: DocTypeAssetStatement, DocTypeRetirementStmt, DocTypeGiftLetter

Credit Agent:

Required: DocTypeCreditReport
Optional: DocTypeDebtPayoff

Collateral Agent:

Required: DocTypeAppraisal
Optional: DocTypePurchaseContract, DocTypeTitleReport, DocTypePropertyInsurance

4. Guidelines Section Mapping

// Load the correct section for your agent
loader.LoadSection("assets")     // For assets agent
loader.LoadSection("credit")     // For credit agent
loader.LoadSection("collateral") // For collateral agent

5. Streaming Output Format

For streaming analysis with real-time progress display, prompts should output markers that StreamFormatter detects. See the streaming-output skill for the full specification.

Key markers:

**📋 GUIDELINE: [Section ID] - [Title]**
Status: ✅ COMPLIANT | ⚠️ ISSUE | ❌ NON-COMPLIANT

**🔍 CROSS-CHECK: [Doc1] vs [Doc2]**
Result: MATCH | MISMATCH

**🧮 INCOME CALCULATION**
Base annual salary: $X,XXX.XX
Total qualifying monthly income: $X,XXX.XX

**✅ FINAL DETERMINATION**
Status: APPROVED | DENIED | NEEDS REVIEW

6. System Prompt Pattern

func (a *Agent) buildSystemPrompt() string {
    // Load guidelines - they contain the analysis instructions
    // Don't duplicate guideline content in the prompt
    if a.guidelines != "" {
        return "## Fannie Mae Guidelines\n\n" + a.guidelines
    }
    return ""
}

7. Response Parsing

Request JSON output and parse into model.AnalysisResult:

type analysisResponse struct {
    Status           string    `json:"status"`
    Confidence       float64   `json:"confidence"`
    Summary          string    `json:"summary"`
    Findings         []finding `json:"findings"`
    Risks            []risk    `json:"risks"`
    MissingDocuments []string  `json:"missing_documents"`
}

8. Register in Main

Update cmd/underwriter/main.go:

import "<agentname>" // Add import

// Create agent
newAgent := <agentname>.NewWithConfig(geminiClient, <agentname>.Config{
    GuidelinesPath: *guidelinesDir,
})

// Add to agents slice
agents := []agent.Agent{incomeAgent, newAgent}

Reference Implementation

Study internal/agent/income/income.go for:

• Complete Analyze() implementation
• Prompt building patterns
• JSON response parsing
• Error handling
• Document filtering

Related Files

• internal/agent/agent.go - Interface definition
• internal/agent/income/income.go - Reference implementation
• internal/model/document.go - Document types
• internal/model/analysis.go - Result structures
• internal/guidelines/loader.go - Guideline loading
• configs/guidelines/ - Guideline files by section