Agent Declarations

[Preview] -- Agent support is in active development. The syntax described here is finalized but the runtime is being implemented.

Grove agents are declared in .grove files alongside your domain model. An agent declaration specifies the model, instructions, available tools, and optional sub-agents.

Prerequisites: Concepts Overview. What you'll learn: How to declare agents, configure their behavior, and connect them to your Grove modules.

Agent Declaration

agent customer_support {
  model "claude-sonnet-4-5-20250929"

  instructions {
    "You are a customer support agent for an e-commerce platform."
    "You can look up orders, process returns, and answer product questions."
    "Always verify the customer's identity before making changes."
  }

  tools {
    lookup_order
    process_return
    search_products
  }
}

Fields

Field	Required	Description
`model`	Yes	The LLM model identifier
`instructions`	Yes	System prompt lines (concatenated)
`tools`	No	List of tool declaration references
`sub_agents`	No	List of agent references for delegation

Connecting to Domain Logic

Agents interact with your Grove modules through tool declarations. When a tool wraps a Grove action, the agent can invoke domain operations with full validation and state machine enforcement.

agent order_manager {
  model "claude-sonnet-4-5-20250929"

  instructions {
    "You manage order lifecycle operations."
  }

  tools {
    create_order
    update_order_status
    cancel_order
  }

  sub_agents {
    shipping_agent
  }
}

Sub-Agents

Agents can delegate to sub-agents for specialized tasks:

agent shipping_agent {
  model "claude-haiku-4-5-20251001"

  instructions {
    "You handle shipping and delivery inquiries."
    "Use tracking tools to find shipment status."
  }

  tools {
    track_shipment
    estimate_delivery
  }
}

The parent agent can invoke sub-agents when a task falls within their specialization. This enables hierarchical agent architectures.

Agent Declarations