Spare Parts Request Agent

Agent-ready recipe for handling equipment failures and spare-part requests in andibase

This recipe tells an agent exactly how to build a spare-parts request workflow in andibase.

The workflow is designed for operations, maintenance, and facilities teams that need to react when equipment fails, identify the right replacement parts, and keep the request moving until the issue is resolved.

Goal

Create four things in one workspace:

An equipment-failure data definition.
A spare-part-request data definition.
A spare-part-request-update data definition.
One agent that triages failures, requests replacement parts, and tracks request progress.

Expected outcome

After following this recipe, the workspace should have:

an equipment-failure definition for reported failures and operational impact
a spare-part-request definition for requested replacement parts
a spare-part-request-update definition for follow-up notes and status changes
a spare-parts-agent agent

Use the API documented in:

Current runtime constraint

The current workspace agent runtime is strong at structured data workflows, but it does not automatically place vendor orders, send procurement emails, or integrate with ERP systems unless those capabilities exist in the execution environment.

That means this recipe should:

record the failure event in workspace data
create and prioritize spare-part requests in workspace data
track operational follow-up and pending actions
mark procurement or vendor contact as pending when external ordering is not available

If a future automation, integration, or external system handles purchasing, it can read the request rows and complete the outbound step later.

Agent instructions

When an agent executes this recipe, it should follow these rules:

Create the equipment-failure definition first.
Create the spare-part-request definition second.
Create the spare-part-request-update definition third.
In the current API, data definition handles are generated from name. Use name: "Equipment Failure", name: "Spare Part Request", and name: "Spare Part Request Update" so the created handles normalize to equipment-failure, spare-part-request, and spare-part-request-update.
If your execution environment can resolve the created definition ids, you may use relationship fields. If it cannot, use text foreign keys such as failureRecordId and requestRecordId, because the public HTTP API still expects dataDefinitionId for relationship fields.
Create the spare-parts agent with instructions focused on triage, replacement-part identification, urgency scoring, and request tracking.
Use the current agent tools. Do not claim that a purchase order, vendor email, or shipment exists unless the execution environment actually completed that step.
If an external procurement step is not available, mark the request as pending with a clear pending reason and next action.
Ask the user only when a missing choice materially changes the request, such as site location, affected equipment, known part number, or severity of downtime.

Step 1: Create the data model

Create three data definitions: equipment-failure, spare-part-request, and spare-part-request-update.

1. Equipment Failure definition

Use name: "Equipment Failure". The current API derives the handle from the name, so this will create the equipment-failure handle.

Recommended fields:

{
  "name": "Equipment Failure",
  "description": "Tracks reported equipment failures, impact, and maintenance context.",
  "fields": {
    "title": {
      "name": "Title",
      "type": "text"
    },
    "siteName": {
      "name": "Site name",
      "type": "text"
    },
    "equipmentName": {
      "name": "Equipment name",
      "type": "text"
    },
    "equipmentCode": {
      "name": "Equipment code",
      "type": "text"
    },
    "failureCategory": {
      "name": "Failure category",
      "type": "select",
      "options": [
        { "value": "mechanical", "label": "Mechanical", "color": "amber" },
        { "value": "electrical", "label": "Electrical", "color": "blue" },
        { "value": "sensor", "label": "Sensor", "color": "violet" },
        { "value": "consumable", "label": "Consumable", "color": "green" },
        { "value": "other", "label": "Other", "color": "zinc" }
      ]
    },
    "severity": {
      "name": "Severity",
      "type": "select",
      "options": [
        { "value": "low", "label": "Low", "color": "zinc" },
        { "value": "medium", "label": "Medium", "color": "blue" },
        { "value": "high", "label": "High", "color": "amber" },
        { "value": "critical", "label": "Critical", "color": "red" }
      ]
    },
    "status": {
      "name": "Status",
      "type": "select",
      "options": [
        { "value": "reported", "label": "Reported", "color": "sky" },
        { "value": "triaged", "label": "Triaged", "color": "blue" },
        { "value": "awaiting-parts", "label": "Awaiting parts", "color": "amber" },
        { "value": "repair-in-progress", "label": "Repair in progress", "color": "violet" },
        { "value": "resolved", "label": "Resolved", "color": "green" },
        { "value": "closed", "label": "Closed", "color": "stone" }
      ]
    },
    "reportedAt": {
      "name": "Reported at",
      "type": "timestamp"
    },
    "reportedBy": {
      "name": "Reported by",
      "type": "text"
    },
    "impactSummary": {
      "name": "Impact summary",
      "type": "text",
      "variant": "long-text"
    },
    "suspectedCause": {
      "name": "Suspected cause",
      "type": "text",
      "variant": "long-text"
    },
    "downtimeMinutes": {
      "name": "Downtime minutes",
      "type": "number"
    },
    "needsSparePart": {
      "name": "Needs spare part",
      "type": "checkbox"
    },
    "activeRequestCount": {
      "name": "Active request count",
      "type": "number"
    }
  }
}

Recommended defaults for agent-created failure rows:

status: reported
reportedAt: now
needsSparePart: true
activeRequestCount: 0

2. Spare Part Request definition

Use name: "Spare Part Request". The current API derives the handle from the name, so this will create the spare-part-request handle.

Recommended fields:

{
  "name": "Spare Part Request",
  "description": "Tracks replacement-part requests created from equipment failures.",
  "fields": {
    "failureRecordId": {
      "name": "Failure record id",
      "description": "Store the linked equipment-failure row id when the client only has public HTTP API access.",
      "type": "text"
    },
    "partName": {
      "name": "Part name",
      "type": "text"
    },
    "partNumber": {
      "name": "Part number",
      "type": "text"
    },
    "quantity": {
      "name": "Quantity",
      "type": "number"
    },
    "requestPriority": {
      "name": "Request priority",
      "type": "select",
      "options": [
        { "value": "low", "label": "Low", "color": "zinc" },
        { "value": "medium", "label": "Medium", "color": "blue" },
        { "value": "high", "label": "High", "color": "amber" },
        { "value": "critical", "label": "Critical", "color": "red" }
      ]
    },
    "requestStatus": {
      "name": "Request status",
      "type": "select",
      "options": [
        { "value": "draft", "label": "Draft", "color": "zinc" },
        { "value": "requested", "label": "Requested", "color": "blue" },
        { "value": "pending-external-order", "label": "Pending external order", "color": "amber" },
        { "value": "ordered", "label": "Ordered", "color": "violet" },
        { "value": "received", "label": "Received", "color": "green" },
        { "value": "cancelled", "label": "Cancelled", "color": "stone" }
      ]
    },
    "vendorName": {
      "name": "Vendor name",
      "type": "text"
    },
    "estimatedUnitCost": {
      "name": "Estimated unit cost",
      "type": "number"
    },
    "requestedAt": {
      "name": "Requested at",
      "type": "timestamp"
    },
    "neededBy": {
      "name": "Needed by",
      "type": "date"
    },
    "reason": {
      "name": "Reason",
      "type": "text",
      "variant": "long-text"
    },
    "recommendedAction": {
      "name": "Recommended action",
      "type": "text",
      "variant": "long-text"
    },
    "pendingReason": {
      "name": "Pending reason",
      "type": "text",
      "variant": "long-text"
    }
  }
}

Recommended defaults for agent-created request rows:

quantity: 1
requestStatus: requested
requestedAt: now

3. Spare Part Request Update definition

Use name: "Spare Part Request Update". The current API derives the handle from the name, so this will create the spare-part-request-update handle.

Recommended fields:

{
  "name": "Spare Part Request Update",
  "description": "Tracks follow-up notes, status changes, and procurement updates for spare-part requests.",
  "fields": {
    "requestRecordId": {
      "name": "Request record id",
      "description": "Store the linked spare-part-request row id when the client only has public HTTP API access.",
      "type": "text"
    },
    "authorName": {
      "name": "Author name",
      "type": "text"
    },
    "updateType": {
      "name": "Update type",
      "type": "select",
      "options": [
        { "value": "triage", "label": "Triage", "color": "blue" },
        { "value": "vendor-note", "label": "Vendor note", "color": "violet" },
        { "value": "status-change", "label": "Status change", "color": "amber" },
        { "value": "receipt", "label": "Receipt", "color": "green" },
        { "value": "internal-note", "label": "Internal note", "color": "zinc" }
      ]
    },
    "body": {
      "name": "Body",
      "type": "text",
      "variant": "long-text"
    },
    "createdAtManual": {
      "name": "Created at manual",
      "type": "timestamp"
    }
  }
}

If your client already has the created definition ids, you can replace the text foreign keys with relationship fields:

{
  "failureId": {
    "name": "Failure",
    "type": "relationship",
    "dataDefinitionId": "<equipment-failure-definition-id>"
  },
  "requestId": {
    "name": "Request",
    "type": "relationship",
    "dataDefinitionId": "<spare-part-request-definition-id>"
  }
}

Step 2: Create the spare-parts agent

Create one workspace agent with handle spare-parts-agent.

Recommended behavior:

review failure details and determine whether a replacement part is needed
create spare-part requests only when the failure likely requires a part
prioritize requests based on severity, downtime, and operational impact
avoid duplicate requests for the same failure and part
update failures to triaged or awaiting-parts when appropriate
leave a clear pending reason when external procurement is still required
keep updates factual and do not invent vendor confirmations or shipment milestones

Recommended agent payload:

{
  "name": "Spare Parts Agent",
  "handle": "spare-parts-agent",
  "description": "Triages equipment failures, creates spare-part requests, and tracks follow-up.",
  "model": "openai/gpt-5.4",
  "capabilities": {
    "webAccess": false,
    "browserAccess": false,
    "objectsAccess": true
  },
  "instructions": "You manage a spare-parts request workflow. Use the equipment-failure, spare-part-request, and spare-part-request-update data definitions as the source of truth. Be action-oriented: make reasonable assumptions, complete the work when the intended outcome is clear, and avoid asking for confirmation on every small step. Review reported failures, identify whether a replacement part is needed, and create spare-part-request rows only when the failure details justify it. Avoid duplicate requests by checking existing requests for the same failure, part name, and part number first. When you create a request, set a practical requestPriority, explain the reason clearly, and store a recommendedAction. If external ordering is not available in the execution environment, set requestStatus to pending-external-order and explain the pendingReason instead of pretending the order was placed. After triage, update the equipment-failure row to triaged or awaiting-parts as appropriate. When updates are added in spare-part-request-update, use them to maintain current status without rewriting historical notes."
}

Create the agent with POST /api/v1/agents.

Step 3: Failure handling flow

Use this operating flow:

A new equipment-failure row is created when a machine, tool, or system fails.
The agent reviews the failure and decides whether a spare part is required.
If a part is needed, the agent creates a spare-part-request row with priority, quantity, and justification.
If external ordering is not available, the request stays in pending-external-order with a clear pending reason.
Maintenance or procurement teammates add follow-up entries in spare-part-request-update.
Once the part arrives and the repair is complete, the request and failure records can be moved to received and resolved.

Recommended acceptance checks

An agent should consider the recipe complete only if all of the following are true:

equipment-failure exists and includes the required fields.
spare-part-request exists and includes either the failureId relationship or the failureRecordId fallback used by the current public HTTP API flow.
spare-part-request-update exists and includes either the requestId relationship or the requestRecordId fallback used by the current public HTTP API flow.
spare-parts-agent exists.
At least one sample equipment-failure row can be created successfully.
At least one request can be created from a failure with a meaningful reason and recommendedAction.
The recipe makes it explicit that external ordering remains pending when no procurement integration is available.

Minimal delivery summary

When the agent finishes, it should report:

the created data definition handles
the created agent handle
whether external ordering is available or still pending
any assumptions made about site operations, equipment naming, or spare-part identification

Spare Parts Request Agent

On this page