# Spare Parts Request Agent (/docs/receipes/spare-parts-request-agent) 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 [#goal] Create four things in one workspace: 1. An `equipment-failure` data definition. 2. A `spare-part-request` data definition. 3. A `spare-part-request-update` data definition. 4. One agent that triages failures, requests replacement parts, and tracks request progress. Expected outcome [#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: * [Data Model](/docs/data-model) * [Get started (for AI Agents)](/docs/agent-get-started) * [Data definitions API](/docs/api-reference/data-definitions) * [Data API](/docs/api-reference/data) * [Agents API](/docs/api-reference/agents) * [Agent Tools](/docs/agent-tools) Current runtime constraint [#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 [#agent-instructions] When an agent executes this recipe, it should follow these rules: 1. Create the `equipment-failure` definition first. 2. Create the `spare-part-request` definition second. 3. Create the `spare-part-request-update` definition third. 4. 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`. 5. 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. 6. Create the spare-parts agent with instructions focused on triage, replacement-part identification, urgency scoring, and request tracking. 7. 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. 8. If an external procurement step is not available, mark the request as pending with a clear pending reason and next action. 9. 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 [#step-1-create-the-data-model] Create three data definitions: `equipment-failure`, `spare-part-request`, and `spare-part-request-update`. 1\. Equipment Failure definition [#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: ```json { "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 [#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: ```json { "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 [#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: ```json { "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: ```json { "failureId": { "name": "Failure", "type": "relationship", "dataDefinitionId": "" }, "requestId": { "name": "Request", "type": "relationship", "dataDefinitionId": "" } } ``` Step 2: Create the spare-parts agent [#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: ```json { "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 [#step-3-failure-handling-flow] Use this operating flow: 1. A new `equipment-failure` row is created when a machine, tool, or system fails. 2. The agent reviews the failure and decides whether a spare part is required. 3. If a part is needed, the agent creates a `spare-part-request` row with priority, quantity, and justification. 4. If external ordering is not available, the request stays in `pending-external-order` with a clear pending reason. 5. Maintenance or procurement teammates add follow-up entries in `spare-part-request-update`. 6. Once the part arrives and the repair is complete, the request and failure records can be moved to `received` and `resolved`. Recommended acceptance checks [#recommended-acceptance-checks] An agent should consider the recipe complete only if all of the following are true: 1. `equipment-failure` exists and includes the required fields. 2. `spare-part-request` exists and includes either the `failureId` relationship or the `failureRecordId` fallback used by the current public HTTP API flow. 3. `spare-part-request-update` exists and includes either the `requestId` relationship or the `requestRecordId` fallback used by the current public HTTP API flow. 4. `spare-parts-agent` exists. 5. At least one sample `equipment-failure` row can be created successfully. 6. At least one request can be created from a failure with a meaningful `reason` and `recommendedAction`. 7. The recipe makes it explicit that external ordering remains pending when no procurement integration is available. Minimal delivery summary [#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 ## Documentation Navigation Use these paths to traverse the relevant docs and generated API reference files for the app. - Spare Parts Request Agent [current] -> `/docs/receipes/spare-parts-request-agent` (source: `content/docs/receipes/spare-parts-request-agent.mdx`) - andibase Overview -> `/docs` (source: `content/docs/index.mdx`) - Get started (for AI Agents) -> `/docs/agent-get-started` (source: `content/docs/agent-get-started.mdx`) - Agent Tools -> `/docs/agent-tools` (source: `content/docs/agent-tools.mdx`) - Agents -> `/docs/agents` (source: `content/docs/agents.mdx`) - Agent Auth -> `/docs/api-reference/agent-auth` - Get agent login request -> `/docs/api-reference/agent-auth/get-api-v1-agent-auth-requests-usercode` - Exchange agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-exchange` - Start agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests` - Approve agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests-usercode-approve` - Deny agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests-usercode-deny` - Agents -> `/docs/api-reference/agents` - Delete workspace agent -> `/docs/api-reference/agents/delete-api-v1-agents-id` - List workspace agents -> `/docs/api-reference/agents/get-api-v1-agents` - Get workspace agent -> `/docs/api-reference/agents/get-api-v1-agents-id` - List agent chats -> `/docs/api-reference/agents/get-api-v1-agents-id-chats` - Get agent chat -> `/docs/api-reference/agents/get-api-v1-agents-id-chats-chatid` - Update workspace agent -> `/docs/api-reference/agents/patch-api-v1-agents-id` - Create workspace agent -> `/docs/api-reference/agents/post-api-v1-agents` - Send agent message -> `/docs/api-reference/agents/post-api-v1-agents-id-chats-chatid-messages` - Apps -> `/docs/api-reference/apps` - Delete app -> `/docs/api-reference/apps/delete-api-v1-apps-id` - List workspace apps -> `/docs/api-reference/apps/get-api-v1-apps` - Get app by id -> `/docs/api-reference/apps/get-api-v1-apps-id` - Update app -> `/docs/api-reference/apps/patch-api-v1-apps-id` - Create app -> `/docs/api-reference/apps/post-api-v1-apps` - Automations -> `/docs/api-reference/automations` - Delete workspace automation -> `/docs/api-reference/automations/delete-api-v1-automations-id` - List workspace automations -> `/docs/api-reference/automations/get-api-v1-automations` - Get workspace automation -> `/docs/api-reference/automations/get-api-v1-automations-id` - List automation runs -> `/docs/api-reference/automations/get-api-v1-automations-id-runs` - Get automation run -> `/docs/api-reference/automations/get-api-v1-automations-id-runs-runid` - Update workspace automation -> `/docs/api-reference/automations/patch-api-v1-automations-id` - Create workspace automation -> `/docs/api-reference/automations/post-api-v1-automations` - Run automation -> `/docs/api-reference/automations/post-api-v1-automations-id-run` - Trigger automation webhook -> `/docs/api-reference/automations/post-api-v1-automations-webhooks-publicid-secret` - Channels -> `/docs/api-reference/channels` - Delete channel -> `/docs/api-reference/channels/delete-api-v1-channels-channelid` - List channels -> `/docs/api-reference/channels/get-api-v1-channels` - Get channel -> `/docs/api-reference/channels/get-api-v1-channels-channelid` - Update channel -> `/docs/api-reference/channels/patch-api-v1-channels-channelid` - Create channel -> `/docs/api-reference/channels/post-api-v1-channels` - Data -> `/docs/api-reference/data` - Data Definitions -> `/docs/api-reference/data-definitions` - Delete data definition -> `/docs/api-reference/data-definitions/delete-api-v1-data-definitions-id` - List data definitions -> `/docs/api-reference/data-definitions/get-api-v1-data-definitions` - Get data definition -> `/docs/api-reference/data-definitions/get-api-v1-data-definitions-id` - Update data definition -> `/docs/api-reference/data-definitions/patch-api-v1-data-definitions-id` - Create data definition -> `/docs/api-reference/data-definitions/post-api-v1-data-definitions` - Data SQL Query -> `/docs/api-reference/data-sql-query` - Run SQL query against workspace data -> `/docs/api-reference/data-sql-query/post-api-v1-data-sql-query` - Get data by id -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-data-id` - Select all data row ids -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-data-select-all` - List data -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-query` - Patch many data rows -> `/docs/api-reference/data/patch-api-v1-data-definitions-definitionid-data-patch-many` - Delete many data rows -> `/docs/api-reference/data/post-api-v1-data-definitions-definitionid-data-delete-many` - Upsert many data rows -> `/docs/api-reference/data/post-api-v1-data-definitions-definitionid-data-upsert-many` - DuckDB Query -> `/docs/api-reference/duckdb-query` - Run a DuckDB query against registered sources -> `/docs/api-reference/duckdb-query/post-api-v1-duckdb-query` - Explorer -> `/docs/api-reference/explorer` - Delete explorer folder -> `/docs/api-reference/explorer/delete-api-v1-workspace-nodes-nodeid` - List explorer nodes -> `/docs/api-reference/explorer/get-api-v1-workspace-nodes` - List explorer folders -> `/docs/api-reference/explorer/get-api-v1-workspace-nodes-folders` - Rename explorer folder -> `/docs/api-reference/explorer/patch-api-v1-workspace-nodes-nodeid-rename` - Create folder -> `/docs/api-reference/explorer/post-api-v1-workspace-nodes-folders` - Move explorer node -> `/docs/api-reference/explorer/post-api-v1-workspace-nodes-nodeid-move` - Files -> `/docs/api-reference/files` - List workspace files -> `/docs/api-reference/files/get-api-v1-files` - Read file content -> `/docs/api-reference/files/get-api-v1-files-fileid-content` - Create file -> `/docs/api-reference/files/post-api-v1-files` - Complete file upload -> `/docs/api-reference/files/post-api-v1-files-fileid-complete` - Presign multipart parts -> `/docs/api-reference/files/post-api-v1-files-fileid-parts` - Update file content -> `/docs/api-reference/files/put-api-v1-files-fileid-content` - Messages -> `/docs/api-reference/messages` - List channel messages -> `/docs/api-reference/messages/get-api-v1-channels-channelid-messages` - List thread messages -> `/docs/api-reference/messages/get-api-v1-channels-channelid-threads-threadid-messages` - Create channel message -> `/docs/api-reference/messages/post-api-v1-channels-channelid-messages` - Create thread message -> `/docs/api-reference/messages/post-api-v1-channels-channelid-threads-threadid-messages` - Notifications -> `/docs/api-reference/notifications` - List notification devices -> `/docs/api-reference/notifications/get-api-v1-notifications-devices` - Check Expo notification receipts -> `/docs/api-reference/notifications/post-api-v1-notifications-receipts` - Send workspace notifications -> `/docs/api-reference/notifications/post-api-v1-notifications-send` - Runs -> `/docs/api-reference/runs` - List workspace runs -> `/docs/api-reference/runs/get-api-v1-runs` - Get workspace run -> `/docs/api-reference/runs/get-api-v1-runs-runid` - Threads -> `/docs/api-reference/threads` - List channel threads -> `/docs/api-reference/threads/get-api-v1-channels-channelid-threads` - Get thread -> `/docs/api-reference/threads/get-api-v1-channels-channelid-threads-threadid` - Create thread -> `/docs/api-reference/threads/post-api-v1-channels-channelid-threads` - Workflows -> `/docs/api-reference/workflows` - Delete workflow definition -> `/docs/api-reference/workflows/delete-api-v1-workflows-id` - List workflow definitions -> `/docs/api-reference/workflows/get-api-v1-workflows` - Get workflow definition -> `/docs/api-reference/workflows/get-api-v1-workflows-id` - Update workflow definition -> `/docs/api-reference/workflows/patch-api-v1-workflows-id` - Create workflow definition -> `/docs/api-reference/workflows/post-api-v1-workflows` - Workspaces -> `/docs/api-reference/workspaces` - Delete workspace API key -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-api-keys-keyid` - Delete workspace credential -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-credentials-credentialid` - Delete workspace invitation -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-invitations-invitationid` - Delete workspace user -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-users-userid` - List my workspaces -> `/docs/api-reference/workspaces/get-api-v1-workspaces` - List workspace API keys -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-api-keys` - List workspace credentials -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-credentials` - List workspace credential tools -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-credentials-credentialid-tools` - List workspace invitations -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-invitations` - List workspace users -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-users` - Create workspace -> `/docs/api-reference/workspaces/post-api-v1-workspaces` - Create workspace API key -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-api-keys` - Create workspace credential -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-credentials` - Invite user to workspace -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-invitations` - Create workspace user -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-users` - Apps -> `/docs/apps` (source: `content/docs/apps.mdx`) - Authentication -> `/docs/authentication` (source: `content/docs/authentication.mdx`) - Building Blocks -> `/docs/building-blocks` (source: `content/docs/building-blocks.mdx`) - Data Model -> `/docs/data-model` (source: `content/docs/data-model.mdx`) - Embedded Host Actions -> `/docs/embedded-host-actions` (source: `content/docs/embedded-host-actions.mdx`) - Introduction -> `/docs/introduction` (source: `content/docs/introduction.mdx`) - Recipes -> `/docs/receipes` (source: `content/docs/receipes/index.mdx`) - Construction Site Visit Agent -> `/docs/receipes/construction-site-visit-agent` (source: `content/docs/receipes/construction-site-visit-agent.mdx`) - Daily Lead Qualification Agent -> `/docs/receipes/daily-lead-qualification-agent` (source: `content/docs/receipes/daily-lead-qualification-agent.mdx`) - Day Planner Agent -> `/docs/receipes/day-planner-agent` (source: `content/docs/receipes/day-planner-agent.mdx`) - Expense Tracker -> `/docs/receipes/expense-tracker` (source: `content/docs/receipes/expense-tracker.mdx`) - Legal Case Tracker -> `/docs/receipes/legal-case-tracker` (source: `content/docs/receipes/legal-case-tracker.mdx`) - Weekly Report Email Agent -> `/docs/receipes/weekly-report-email-agent` (source: `content/docs/receipes/weekly-report-email-agent.mdx`) - UI Components -> `/docs/ui-components` (source: `content/docs/ui-components.mdx`)