How to set up AI Studio 2.0 and use it day to day. Screen names are shown in bold, exactly as they appear in Shipwell.
Who this is for
AI Studio has three kinds of user. Most companies have one or two people in each role.
Role | What they do | Permission they need | Read |
Admin | Gives people access, sets up Workers and connects mailboxes | AI Studio: Edit, Create and Delete | 1, 3, 4, 5, 7 |
Billing owner | Buys credits, sets spending limits, downloads receipts and statements | AI Studio Billing. No AI Studio permission is needed. | 2, 7 |
Ops user | Chats with Workers, approves their actions and reviews their work | AI Studio: View. Approvers also need the Shipwell permission the action uses. | 6 |
Anyone with AI Studio View can read every Worker's conversations in Activity. The Billing and Analytics toggles don't need View, so finance or reporting staff can have those pages without seeing conversations.
1. Give people access
For admins. Company admins have AI Studio access from day one. Everyone else starts with none until an admin grants it.
In Shipwell, open your company's Users page and select the person.
In the permissions table, find the AI Studio row and tick what they need:
View: see every Worker and its Activity.
Edit: change Workers, Skills, Knowledge, Tools and Channels.
Create and Delete: add and remove Workers.
Expand AI Studio Enablements. Turn on AI Studio Billing for anyone who buys credits, sets spend limits or manages the saved card, and AI Studio Analytics for anyone who needs usage reports. These toggles work on their own; they don't depend on the AI Studio permissions above.
Save.
2. Add credits and set spend limits
For billing owners. Workers and Document AI spend credits from one balance for your whole company. When the balance reaches zero, Workers pause: runs already in progress finish, and new work waits until you add credits.
A credit costs $0.01. For what uses credits, what's free and typical costs, see AI Studio and Document AI: Pricing.
Check your balance. Open AI Studio › Billing. The Overview tab shows four things:
Balance
Lasts: how long the balance should last at your recent rate
Automatic top-up status
Default card
Buy credits by card.
Select Buy credits.
Choose a pack (250,000, 500,000, 1,000,000 or 2,500,000 credits) or Custom amount. Each option shows how long it would last at your current rate.
Select Continue to payment. The Payment step shows the credits, estimated sales tax and Total due today. Under Pay with, choose a saved card or add one, then confirm. Credits land on your balance as soon as payment clears.
Shipwell will never ask for your card number by phone, email or chat. Cards are only ever entered in the Buy credits or Add card form.
Buy credits by invoice. Ask your Shipwell account team. They'll invoice you, and the credits are added to your balance once the invoice is paid.
Set automatic top-up and a monthly limit.
On Overview, select Turn on under Automatic top-up, or switch on the toggle in the Automatic top-up section lower on the page.
Fill in the four fields:
Top up when balance falls below: the trigger point, in credits.
Refill the balance to: the balance to bring it back up to.
Spend no more than per month (USD): your hard monthly ceiling.
Top-ups per month: the most top-ups allowed in a month.
Select Save.
Automatic top-up always charges the default card, which you set on the Payment methods tab. Once the monthly ceiling is reached, no more top-ups happen that month, and Workers pause when the balance runs out.
Below the fields, a summary spells out what your settings will do, for example "Below 100,000 credits, top the balance back up to 500,000." Each field also shows a hint, such as how many credits one top-up adds. If this month's limits are used up, a banner reads No more automatic top-ups this month; raise the limits to allow more. See payment history lists past top-ups.
3. Turn on a Certified Worker
For admins. Shipwell Certified Workers are marked Certified Worker. Shipwell builds and maintains them, so their identity, instructions, model, skills and tools can't be changed. You decide how they reach people, when they run, and who approves their actions.
Available at launch: Settlement Prep, Pricing Analyst. Coming soon: Track & Trace, Appointment Scheduler, Order-to-Shipment Planner and Insight Generation.
Open AI Studio › Worker Library, then the Worker Library tab, and find the Worker.
Open the menu on its card and select Edit. This opens Configure.
Work down the cards. Changes apply to the live Worker as soon as they're saved.
Identity and Instructions: shown for reference and greyed out, because Shipwell maintains them. A note at the top of the page says so.
Channels: the label next to the Channels title, for example Chat, sums up how people can reach the Worker. Chat is on for anyone in your company. Virtual Inbox gives the Worker its own email address; add allowed senders to its allowlist. A channel can't start a run until its allowlist has at least one address. Mailboxes you connect yourself are managed on the Channels page (see section 4).
Triggers: select Add Trigger, then Schedule, to run the Worker on its own, for example every morning. Each schedule shows when it next runs, with a toggle to pause it, Edit to change it, and View runs to see its past runs. Event is greyed out until event triggers arrive.
Document processing: shows how the Worker reads documents, for example Use company default.
Tools: each tool shows whether it Runs without approval or Needs approval, and who approves it, for example admins. Select the arrow next to a tool to see more.
Communication policy: the summary next to the title, for example "no flows · any time · 3/day per address", shows the current settings. Under Rules, May email lists who the Worker can email: people in the conversation, contacts from Shipwell records, and any addresses you add under Also allowed with + Add an address. Anyone else is blocked before sending, and before any approval is requested: nothing is sent, and the Worker tells you which rule stopped it. Contact hours is Any time or Business hours, and applies only to emails to people outside your company. Rate cap limits how many emails one address can get from this Worker in 24 hours. Flows are default plans for an outreach. With no flows, the Worker doesn't follow up on its own and never escalates.
Conversation starters: one-line suggestions people see when they open a chat with the Worker. Select Generate or Add Starter, and drag them to reorder.
Check that the Worker shows Active on its card.
4. Connect an email channel
For admins. A Worker can email from an address of its own, or from your company's mailbox.
Option A: the Worker's own address (Virtual Inbox). On the Worker's Configure page, turn on Virtual Inbox under Channels. Mail sent to that address appears in the Worker's Activity and can start a run. If you haven't connected a mailbox, it's also the address the Worker sends from. Inbound mail must pass a sender check (DMARC, or DKIM and SPF).
Option B: a company mailbox (Gmail or Outlook).
Open AI Studio › Channels and select Connect a channel.
Under Email, select Sign in with Google or Sign in with Microsoft, and sign in to the mailbox the Worker should use.
Back on Channels, expand the mailbox. It shows which Worker it's Assigned to, its Permissions (for example Read and send email) and who connected it. Use Change Worker or Unassign to move it, and Disconnect to remove it.
Under Who can message this Worker here, choose Anyone who has the address or Allowlist only. If you choose the allowlist, add at least one address.
Each mailbox serves one Worker, and each Worker uses one mailbox. Slack, Microsoft Teams and text messages (SMS) are listed under Coming soon.
To find mailboxes that need setting up, use the filters above the list: All, Needs attention and Unassigned.
5. Build your own Worker
For admins with Create permission. Build a custom Worker when no Certified Worker fits.
Open AI Studio › Worker Library and select Start Building under Start from Scratch. A New worker page opens as a Draft.
Identity: enter a Display name and a Description. The Worker gets its own user in Shipwell. Then, in the Worker type card, pick an existing type, or type a new one to add it to the list.
Instructions: describe what the Worker should do in plain words, then select Generate to expand that into full instructions. Use Write to edit them and Preview to read the result. The model defaults to
openai/gpt-5.4.Tools: select Add Tool and grant only what the Worker needs. A Worker that only reads data can't change anything.
Skills: select Add Skill to attach a packaged instruction, with its tools bundled in.
Channels and Document processing: set these the same way as in sections 3 and 4.
Conversation starters: add a few example questions, or select Generate.
Access: select Add User to choose who can edit, test, publish and manage access for this Worker. Everyone else on your team can only view it.
Select Save draft, then Test to try it. Once it's saved, you can add a schedule under Triggers. When it's ready, Publish it. A custom Worker goes live only once it's published.
Or build it in conversation. Open Worker Builder in the side panel and describe what you need in plain words. For example: "Build me a Worker that ingests documents and matches them to shipments, then tells me which shipments are missing invoicing documents." Worker Builder checks whether it has enough to go on, chooses the skills and tools, and fills in the page as it goes. Review each card before you save.
Tips. Larger models cost more credits per step, so keep the default unless you need more. Give a Worker the fewest tools that do the job, and require approval for anything that writes to Shipwell or sends email.
6. Work with Workers day to day
For ops users. There are three ways to work with a Worker:
chat with it
send it email
check on it in Activity, where you approve what it wants to do
Chat with a Worker. Open chat from Ask Swifty in the left nav, or from the Ask Swifty tab on the right edge of the screen. The Worker's name is at the top of the chat panel; select it to choose which Worker to chat with. Pick a conversation starter, or type your request.
To hand a Worker documents, attach them to your message. While it works, the chat shows what it's doing, such as "Reading KRA92P_demo_invoice_packet.pdf · Step 4 of 7". When it's done, select the step summary at the top of its reply (for example "Checked documents, document_store and shipments · 15 steps") to see every tool it called. Tables in a reply have a Download CSV link. Chat is a record of what happened, so messages can't be edited or deleted.
Find a conversation. Open AI Studio › Activity. Each row is one conversation (a thread), with its ID, Worker, trigger, credits and last activity. Narrow the list with Search, Worker, Person, Time range, Trigger, Source or Channel. Four views sort out what needs you:
View | Shows |
All threads | Every conversation |
Needs approval | Actions waiting for an approver |
Waiting on me | Items you personally need to act on, soonest deadline first |
Overdue | Items past their expected time |
Read a thread. Select a thread ID to open its record. The record has three parts:
Timeline: every message and action, grouped into runs. Each run shows its credits, for example RUN 3 · 29 CREDITS. A line such as "Called documents.search, document_store.get" opens to show each step the Worker took.
Run facts: the Worker, trigger, channel, number of runs, total credits and duration.
Continue in chat picks the conversation back up. Copy ID copies the thread ID, for example THR-7A8BC8F0, so you can share it with a colleague or with Shipwell support.
Approve or reject an action. When a Worker wants to take an action that needs approval, its thread is marked Needs approval and shows how long is left to decide. It appears under Needs approval and Waiting on me in Activity. Waiting on me lists the soonest deadline first.
Open the thread. The request is at the end of the timeline. For an email, the card reads Send this email? and shows From, To, Subject and Body, with a reminder that the email goes out at once and can't be recalled.
Check the Approval panel on the right: the tool, who can approve, and the time left.
Select Approve or Reject. Any listed approver can decide; the first decision counts.
If you asked the Worker in chat, the same request also appears there, with Accept and Decline.
Before the action runs, the Worker re-checks the record. If something important changed since the request, for example a shipment's weight, the action doesn't run. The step reads Not run — what it acts on changed, and the Worker tells you what changed and offers to propose the action again with the current data. If nobody decides in time, the request expires and the Worker says so in the thread. An approver can still approve it later from Activity.
Work with documents. Workers read documents through Document AI, so there's nothing to set up:
Attach a document in chat, or email it to the Worker's inbox. In chat, the attachment shows its progress, then a check mark once it's been read.
Document AI extracts the text, key fields with a confidence score for each, and any signatures. A PDF that holds several documents, such as an invoice, a BOL and a POD, is split into its parts.
The Worker works from those results: matching documents to shipments, attaching them, or reporting what's missing.
Every document a Worker reads is filed in Document AI › Documents, under System, in a folder for its conversation. Open it there to see the full extraction. Admins choose how conversation files are read under AI Studio › Document Config; a Certified Worker uses its own profile.
7. Track usage and cost
For admins and billing owners. Analytics shows where credits go. Billing keeps the money records.
Analytics (needs the AI Studio Analytics toggle). Open AI Studio › Analytics. Use Filters to narrow the time window, and Export CSV to download. The page shows:
Credits consumed — daily, against your daily average.
Usage activity by Worker: credits, runs and threads for each Worker.
Where the credits went: model work (LLM tokens) against document reading (Documents), by week.
What triggered the consumption: which inbox, person or schedule caused the work.
Worker detail: runs, credits per thread and typical duration for each Worker, compared with the previous 30 days.
Credits per thread is the closest measure of what one task costs. Compare it with the estimate you were given at signing.
Statements and receipts. Open Billing › Statements & History.
Statements: one per month, showing credits used, credits added and the net change. While the month is open it reads In progress, with the date it closes; you can download it a few days after month-end. A statement shows what the credits were spent on and carries no balance due.
Billing History: a row for every purchase, with its receipt as proof of payment. Credits Shipwell adds at no charge show as a Grant.
Invoiced customers get their invoice from Shipwell's billing system, not from AI Studio.
Coming soon
These aren't in AI Studio yet. If you don't see them, nothing is wrong with your account.
Knowledge: give Workers reference material to work from. It shows in the nav as "Coming soon".
More channels: Slack, Microsoft Teams and text messages (SMS), listed under Coming soon in Connect a channel.
Event triggers: start a Worker when something changes in Shipwell, such as a shipment's status. Event shows under Add Trigger but is greyed out until then.
Worker memory: Workers keep useful facts from past conversations, such as a carrier's preferred contact or a facility's receiving hours, and use them the next time.
Troubleshooting
What you see | Why | What to do |
Workers stopped running | The credit balance is zero | Buy credits, or raise the monthly ceiling on automatic top-up |
Email to the Worker doesn't start anything | The channel's allowlist is empty, or the sender isn't on it | Add the sender under Allowlist only, or switch to Anyone who has the address |
"Blocked by the Rules, nothing sent: a recipient isn't allowed" in chat or a thread | The Worker tried to email an address that isn't in the conversation, isn't in your Shipwell records and isn't on Also allowed | If the address is legitimate, add it under Communication policy › Also allowed |
A request never ran | Its approval expired | Approve it from Activity, or reply in the thread so the Worker tries again |
"Not run — what it acts on changed" | The record changed between the request and the approval | Ask the Worker to propose it again; the new request uses the current data |
A document shows "Processing failed" | Document AI couldn't read the file | Upload it again, ideally the original PDF. Send a multi-document packet as separate files. |
A Worker can't find data you expect | It doesn't have the tool, or the data isn't in Shipwell | Admins: check the Worker's Tools card. Workers only see data in Shipwell. |
"No more automatic top-ups this month" on Billing | This month's spending limit or top-up count has been used | Raise the limits in Automatic top-up, or buy credits. Limits reset on the 1st of each month. |