Agentic Feature Design

Features in LivestockAI must now be designed for dual consumption: Humans (UI) and Agents (MCP/API).

1. The "Headless First" Rule

Every feature must be fully functional via Server Functions before any UI is built.

Test: Can an agent complete the entire user story using only

bun run check-feature-x.ts

(a script calling server functions)? If yes -> Agent Ready. If no (logic lives in React components) -> Refactor immediately.

2. Agent-Ready Server Functions

Server functions are the tools we give to agents. Document them accordingly.

export const createBatchFn = createServerFn({ method: 'POST' })
  .inputValidator(batchSchema)
  .handler(async ({ data }) => {
    /* ... */
  })

/**
 * @description Creates a new livestock batch.
 * @workflow
 * 1. Check `getFarmFacilities` for space.
 * 2. `createBatchFn`
 * 3. Log initial `feed_record` if applicable.
 */

3. The "Intention" Pattern

Agents operate on Intent, not just data. Instead of generic CRUD (

updateBatch

), expose semantic actions (

graduateBatch

,

quarantineBatch

).

// ❌ Generic
updateBatch(id, { status: 'sold' })

// ✅ Semantic (Agent Friendly)
markBatchAsSold(id, { date, price, customer })

Semantic actions allow agents to:

1. Understand the consequences of the action.
2. Perform specialized validation (e.g. "Can't sell a quarantined batch").

4. Approval Loops (Human-in-the-Loop)

Agents need a standard way to ask for permission for high-stakes actions (e.g., ordering feed, selling stock).

The

ApprovalRequest

Entity:

• agentId

  : Who is asking?

• action

  : JSON payload of the server function to call.

• summary

  : Human-readable explanation ("I want to order 50 bags of Starter Feed").

• status

  : PENDING | APPROVED | REJECTED

5. Metadata for Context

All major entities (

Batches

,

Sales

) should have an

ai_metadata

JSONB column. Agents use this to store reasoning ("Predicted harvest date change due to low feed intake"). Do not show this raw JSON to users, but use it to power UI "Insights".

Related Skills

• three-layer-architecture

  - Where the logic lives

• feature-structure

  - How to organize the files