[Docs index](/docs.md) / [Subagents](/docs/subagents/overview.md) / Playbook: Build a Vendor Intake Coordinator --- # Playbook: Build a Vendor Intake Coordinator Onboarding a new vendor is supposed to be simple. Somebody in operations identifies a vendor they want to work with, the vendor sends over their info, legal reviews the agreement, finance collects a W-9 and sets them up in the ERP, and procurement issues the first PO. In practice, every step happens in a different system — email, a shared drive, a SharePoint form, a spreadsheet, the ERP — and somebody is always copying data from one place to another. A new vendor takes three weeks to onboard. Half of that is real review work; the other half is waiting for someone to remember to do the next handoff. Vendors get frustrated. Procurement gets frustrated. Finance ends up doing a backlog cleanup at month end. This playbook walks you through replacing the spreadsheet-and-email shuffle with a single sandcastle app driven by a dedicated subagent. Vendors fill out a form in the app. The subagent picks it up, drives every downstream step, and posts status updates so everyone can see where things are without having to ask. ## What you will build By the end of this playbook, you will have: - A sandcastle app called **Vendor Intake** with a vendor-facing intake form and an internal kanban view. - A subagent called **Vendor Intake Coordinator** linked to the sandcastle, with read/write access to the intake state collection. - A workflow that takes a new submission through stages: `submitted` → `under_legal_review` → `awaiting_w9` → `setup_in_erp` → `active`. - Custom tools that integrate with your legal review queue, your document collection service, and your ERP. - A scheduled trigger that nudges stuck items every morning. - Status updates posted to `#procurement-ops` Slack so the team always knows what's where. ## What you need before you start - An Assist workspace with your AI client connected via MCP. - A way to send a document for legal review (a tool that posts to your legal team's queue, or even an email integration if that's how legal works today). - A document collection service (Docusign, HelloSign, an internal portal — any tool that can request a W-9 and tell you when it's signed). - API access to your ERP for vendor creation. Use a service account with vendor-create permissions only. - The Slack bot in your `#procurement-ops` channel. - Permission to create sandcastles in your workspace. This playbook builds the sandcastle and the subagent in tandem, because each one is built around the other. You will iterate between them. ## Step 1: Sketch the sandcastle Open your AI client and describe what you want: > "I want to build a sandcastle called Vendor Intake. It needs: > > - A public form at `/intake` where a vendor enters their company name, primary contact name, primary contact email, address, EIN, and a brief description of what they sell. Submitting the form creates a row in a state collection called `vendor_intakes` with status `submitted`. > - An internal kanban view at `/dashboard` that shows all rows in `vendor_intakes` grouped by status. Cards show vendor name, contact, days since submission, and a 'Open' button that drills into the full record. > - A detail page at `/dashboard/[id]` that shows everything we know about the vendor, every status transition with a timestamp, and a comment thread. > > The state collection schema should include: id, company_name, contact_name, contact_email, address, ein, description, status (enum), submitted_at, status_history (array of {status, at, by, note}), and a generic notes field." The client builds the sandcastle. You may need to iterate on the form layout, the kanban styling, and the schema. Spend the time here — the sandcastle is the surface everyone else will see, so it should look right and feel right. ## Step 2: Build the integration tools These tools drive the workflow. Build them in `/tools/new`, test each one on its edit page, and publish before wiring to the agent. Because this workflow includes a **write** call against the ERP, be especially deliberate — scope the credential to vendor-create only, and test extensively on the edit page before publishing. The [shared toolbox playbook](playbook-organization-toolbox.md) covers the full build/test/publish pattern. Each blockquote below is the **spec** for one tool. ### Legal review > **`legal_request_review`** — takes `vendor_name`, `contact_email`, `description`, and `intake_id`. POSTs to `https://legal.internal.company.com/api/reviews` with those fields plus `source: 'vendor_intake'`. Returns a `review_id`. Uses the secret `LEGAL_API_TOKEN`. > **`legal_get_review_status`** — takes a `review_id` and returns the current status (`pending`, `approved`, `rejected`, `needs_clarification`) plus the reviewer's notes if any. ### Document collection > **`docs_request_w9`** — takes `recipient_email`, `recipient_name`, and `intake_id`. Calls the document service at `https://docs.internal.company.com/api/request` with template `w9_v3` and returns a `request_id`. > **`docs_get_request_status`** — takes a `request_id` and returns the status (`sent`, `viewed`, `signed`, `expired`) plus the signed document URL if completed. ### ERP setup > **`erp_create_vendor`** — takes `company_name`, `address`, `ein`, `contact_email`, and `w9_document_url`. POSTs to `https://erp.internal.company.com/api/vendors` and returns the new vendor's ERP id and the vendor record. Uses the secret `ERP_VENDOR_TOKEN`. This is the only write call against the ERP — keep the credential's scope narrow and test carefully before publishing. Test each tool on its edit page with known-good fake input. Confirm responses look right. Publish each tool before moving on. ## Step 3: Create the subagent and link it to the sandcastle Go to **Subagents > New Agent**: - **Label**: `Vendor Intake Coordinator` - **Description**: `Drives the vendor intake workflow end-to-end. Submits new vendors for legal review, requests W-9s, creates ERP vendor records, posts status updates to #procurement-ops.` - **Job Description**: (we will add a long, detailed prompt in the next step — for now, put a placeholder). - **Tools**: `legal_request_review`, `legal_get_review_status`, `docs_request_w9`, `docs_get_request_status`, `erp_create_vendor`, `slack_send_message`. - **Model**: a capable model. Save it. Now link it to the sandcastle. From the sandcastle's edit page, set the **Coordinator Subagent** (or equivalent linking field) to **Vendor Intake Coordinator**. The agent now has read/write access to the sandcastle's `vendor_intakes` state collection through automatically-granted state tools. ## Step 4: Write the orchestration prompt Open the agent's edit page and replace the placeholder job description with the real one: > You coordinate vendor intake. Every record in the `vendor_intakes` state collection passes through your hands as it moves from `submitted` to `active`. You are the only writer to the workflow's status field; humans update notes and override status only through the kanban app. > > The workflow: > > - **submitted**: a vendor just filled out the form. Call `legal_request_review` with their info. On success, store the `review_id` in the record's notes field as `legal_review_id` and transition status to `under_legal_review`. Post to `#procurement-ops`: "New vendor: {company_name}. Sent to legal." > > - **under_legal_review**: poll `legal_get_review_status` using the stored `review_id`. If `approved`, transition to `awaiting_w9` and call `docs_request_w9` with the contact info. Store the `request_id` as `w9_request_id`. Post to `#procurement-ops`: "{company_name}: legal approved. W-9 requested." If `rejected`, transition to `rejected` with the reviewer notes. Post to `#procurement-ops`: "{company_name}: legal rejected. Reason: {notes}." If `needs_clarification`, post the reviewer notes to `#procurement-ops` and tag `@procurement-leads` for human follow-up — do not transition status. > > - **awaiting_w9**: poll `docs_get_request_status`. If `signed`, fetch the signed document URL, transition to `setup_in_erp`, and call `erp_create_vendor` with the vendor info and the W-9 URL. Store the returned `erp_vendor_id` in the record. Post to `#procurement-ops`: "{company_name}: W-9 received. Created in ERP as vendor {erp_vendor_id}." Transition to `active`. If `expired`, transition back to `awaiting_w9` and call `docs_request_w9` again with a fresh request, capping at three retries before escalating to `@procurement-leads`. > > - **active**: terminal state. Do nothing. > > - **rejected**: terminal state. Do nothing. > > When you transition status, always append to the record's `status_history` array with the new status, the current timestamp, your name ("Vendor Intake Coordinator"), and a one-sentence note describing why the transition happened. > > Never modify a record manually if status is being driven by a human — check the most recent `status_history` entry; if `by` is a human user, ask before changing anything. Save the agent. ## Step 5: Test the happy path In a chat with the agent, simulate a new submission: > "A new vendor just submitted: company 'Acme Test Co', contact 'Jane Doe', email 'jane@acmetest.example', EIN 12-3456789, address '123 Main St', description 'Office supplies'. Add a record to `vendor_intakes` with status `submitted` and run the workflow forward." The agent should: 1. Add the record. 2. Call `legal_request_review`. 3. Store the review id. 4. Transition to `under_legal_review`. 5. Post to `#procurement-ops`. Now manually mark the legal review as approved in the legal system (or use a test mode of the tool that auto-approves). Tell the agent: > "Re-check Acme Test Co." It should call `legal_get_review_status`, see the approval, transition to `awaiting_w9`, and call `docs_request_w9`. Continue through the W-9 step and the ERP creation. By the end, the record should be `active`, the ERP should have a new vendor row, and `#procurement-ops` should have a clean trail of three or four status posts. ## Step 6: Schedule the polling The agent now drives forward when you tell it to. Make it self-driving by scheduling regular polling. Open the agent's chat: > "Schedule yourself to run every weekday at 9:00 AM, 1:00 PM, and 4:00 PM America/New_York with the prompt: 'Read every record in vendor_intakes that is not in a terminal state. For each, do whatever the next step is in the workflow. Post a single summary to #procurement-ops at the end with how many records moved.' Call the trigger 'Workflow Tick'." Three runs a day is enough for most onboarding workflows — vendor responses tend to come in within hours, not minutes. If your team needs faster, schedule more. ## Step 7: Add a morning nudge for stuck items Some vendors stall — they get the W-9 request and never sign it. Add a separate scheduled run for nudging: > "Schedule another run, daily at 8:00 AM America/New_York, with the prompt: 'Find every record in vendor_intakes where status hasn't changed in 5+ days. For each, post to #procurement-ops with the vendor name, current status, and days stuck.' Call this 'Stuck Items Digest'." The procurement team gets a Monday-morning view of who needs a manual nudge — without anyone having to write a query or open the kanban. ## What you built You have a vendor intake system that: - Replaces the email/spreadsheet shuffle with a single app driven by a single agent. - Moves a typical vendor through the workflow in hours instead of weeks, because every handoff happens automatically. - Gives the procurement team one place to look — the kanban — to see where any vendor is. - Posts status to Slack as work happens, so nobody has to ask "where is the Acme onboarding". - Keeps a complete `status_history` audit trail on every record, satisfying the compliance review that comes once a year. - Runs in your Assist workspace under your control — credentials live in the workspace, every state transition is logged, and the kanban app inherits your workspace permissions. The procurement team gets time back. Vendors get onboarded faster. Finance stops doing month-end cleanup. ## Where to go from here - **Add a contracts step.** Insert `awaiting_signed_msa` between `under_legal_review` and `awaiting_w9` for vendors that need an MSA. - **Add a banking step.** Add `awaiting_banking_info` for vendors that need ACH setup before they can be paid. - **Build a procurement dashboard subagent.** A separate subagent that reads `vendor_intakes` and produces weekly aging reports, vendor-type breakdowns, and bottleneck analysis. - **Vendor-facing status page.** Extend the sandcastle with a vendor-facing page where they can check their own onboarding status with a magic link emailed at submission time. ## Related guides - [Creating a subagent](creating-a-subagent.md) - [Scheduling a subagent](scheduling-a-subagent.md) - [Routing channels to a subagent](routing-channels-to-a-subagent.md) - [Troubleshooting](troubleshooting.md) --- ## Navigation ### In this section: Subagents - [Subagents](/docs/subagents/overview.md) - [Use Cases and Playbooks](/docs/subagents/use-cases.md) - [Troubleshooting](/docs/subagents/troubleshooting.md) - [Adding Tools to a Subagent](/docs/subagents/adding-tools-to-a-subagent.md) - [Creating a Subagent](/docs/subagents/creating-a-subagent.md) - [Delegating to a Subagent](/docs/subagents/delegating-to-a-subagent.md) - [Managing Subagent Access](/docs/subagents/managing-subagent-access.md) - [Routing Channels to a Subagent](/docs/subagents/routing-channels-to-a-subagent.md) - [Scheduling a Subagent](/docs/subagents/scheduling-a-subagent.md) #### Playbooks - [Playbook: Build a Shared Toolbox for Your Organization](/docs/subagents/playbook-organization-toolbox.md) - [Playbook: Build a Tier-1 Support Triage Subagent](/docs/subagents/playbook-tier-1-support-triage.md) - **Playbook: Build a Vendor Intake Coordinator** (current) - [Playbook: Build an Ops Channel Concierge in Slack](/docs/subagents/playbook-ops-channel-concierge.md) - [Playbook: Build an Overnight Reconciliation Agent](/docs/subagents/playbook-overnight-reconciliation-agent.md) ### Other sections - [MCP Servers](/docs/mcp-servers/overview.md) - [Tool Creation](/docs/tool-creation/overview.md) - [Agent Filesystem](/docs/agent-filesystem/overview.md) - [Chat Sharing](/docs/chat-sharing/overview.md) - [Scheduled Triggers](/docs/scheduled-triggers/overview.md) - [Agent Skills](/docs/agent-skills/overview.md) - [Sandcastles](/docs/sandcastles/overview.md) - [Workspace Permissions](/docs/workspace-permissions/overview.md) [Back to docs index](/docs.md)