Agentic Patterns

[Preview] -- These patterns document the intended usage of Grove's agent system.

Common architectural patterns for building AI agent applications with Grove. Each pattern combines agents, tools, workflows, and domain logic into a reusable architecture.

Prerequisites: Agent Declarations, Tool Declarations. What you'll learn: Proven patterns for agent-driven applications.

Pattern 1: Domain Expert Agent

A single agent with tools that wrap a specific Grove module's actions and queries.

// The agent has full access to one domain
agent inventory_manager {
  model "claude-sonnet-4-5-20250929"
  instructions {
    "You manage product inventory. You can check stock levels,"
    "adjust quantities, and flag low-stock items."
  }
  tools {
    check_stock
    adjust_quantity
    list_low_stock
    add_product
  }
}

When to use: Single-domain operations where the agent needs deep access to one module.

Pattern 2: Orchestrator with Sub-Agents

A top-level agent delegates to specialized sub-agents based on the task.

agent customer_service {
  model "claude-sonnet-4-5-20250929"
  instructions {
    "You are the primary customer service agent."
    "Route order questions to the order agent."
    "Route shipping questions to the shipping agent."
    "Handle general inquiries yourself."
  }
  tools {
    lookup_customer
  }
  sub_agents {
    order_agent
    shipping_agent
    billing_agent
  }
}

When to use: Multiple domains where different expertise is needed. The orchestrator decides which sub-agent to invoke.

Pattern 3: Workflow-Triggered Agent

An agent is invoked as part of a workflow when human-like judgment is needed.

// Workflow invokes agent for classification
workflow triage_support_ticket v1 {
  node classify = classify_ticket v1
  node route = route_to_team v1
  edge classify -> route
}

// Activity uses agent to classify
activity classify_ticket v1 {
  data classification {
    // Agent invocation as an activity step
    host classify_with_agent {
      ticket_text: input.description
      categories: ["billing", "technical", "shipping", "general"]
    }
  }
  apply(input: TicketInput) -> ClassificationResult {
    return { category: classification.category, confidence: classification.confidence }
  }
}

When to use: Workflows that need AI judgment at specific steps, while keeping the overall flow deterministic.

Pattern 4: Human-in-the-Loop with Agent Assist

An agent prepares recommendations, but a human approves the action.

agent refund_advisor {
  model "claude-sonnet-4-5-20250929"
  instructions {
    "Analyze refund requests and recommend approval or denial."
    "Provide reasoning for your recommendation."
    "You CANNOT approve refunds directly -- only recommend."
  }
  tools {
    lookup_order
    check_return_policy
    calculate_refund_amount
  }
}

The agent's recommendation feeds into an approval workflow that uses signal to wait for human approval.

When to use: High-stakes decisions where AI provides analysis but humans make the final call.

Pattern 5: Data Pipeline Agent

An agent processes incoming data (webhooks, API calls) and routes it through domain actions.

agent webhook_processor {
  model "claude-haiku-4-5-20251001"
  instructions {
    "Process incoming webhook events."
    "Map external event data to internal domain actions."
    "Handle format variations gracefully."
  }
  tools {
    create_order
    update_payment_status
    record_shipping_event
  }
}

When to use: Integration points where incoming data is semi-structured and needs intelligent mapping.

Choosing a Pattern

See Also

• Agent Declarations -- Agent syntax reference
• Tool Declarations -- Tool syntax reference
• Prompt Evaluation -- Testing agent quality
• Workflows -- Workflow orchestration