Developer Cookbook
Integration recipes for ISVs and developers building on AIOS. Connect a visitor app to chat for structured search and form prefill.
Open the visitor demo (Chinese)Set up an app
Build the app interface and business logic first, then declare its tool for chat. The visitor demo currently has the protocol enabled.
- Prepare a visitor-facing artifact app and add it to a dedicated test role’s visible apps.
- As an organization admin, patch the existing app through
POST /api/apps?patch=1. Match names and fields to your test workspace. Declare only reference fields that visitors can read. - An admin enables the customer service tool protocol in the visitor role settings. It is off by default. Use the demo if the trial is unavailable in your workspace.
Search exhibitors
The lookup operation combines a keyword with a hall filter. This minimal example uses name, hall, booth, and products. A row can contain “B1 Supply Chain Hall” while the filter passes B1.
查 B1 展馆有哪些工业机器人的展商
Expect one result in the B1 card with “工业机器人” set as the keyword: 东麓分拣, booth B1-26.
App configuration
{
"name": "Exhibitor Search",
"mode": "artifact",
"受众": "访客",
"客服工具": {
"version": 1,
"name": "visitor_exhibitors_search",
"description": "Find exhibitors by product, name or booth. Pass both the hall and keyword when provided.",
"parameters": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"maxLength": 80,
"description": "Product, exhibitor or booth. Omit for an entire hall."
},
"filters": {
"type": "object",
"properties": {
"hall": {
"type": "string",
"maxLength": 8,
"description": "Hall code, for example B1."
}
},
"required": [],
"additionalProperties": false
}
},
"required": [],
"additionalProperties": false
},
"operation": {
"kind": "lookup",
"table": "Exhibitors",
"keywordFields": [
"name",
"products",
"booth"
],
"filters": {
"hall": {
"field": "hall",
"match": "first-word"
}
},
"sortField": "booth",
"resultFields": [
"name",
"hall",
"booth"
]
}
},
"type": "Exhibitors",
"可读表": [
{
"type": "Exhibitors",
"字段": [
"name",
"hall",
"booth",
"products"
],
"最多": 40
}
]
}Read query results in the app
const { 参数: query = {}, 结果: result } = await aios.context()
if (result) renderResults(result.rows, result.total, query)Connect the fragment to your own renderResults. Supply a default view when the app opens directly. Keep the original filters visible for empty results.
Prefill an invoice draft
Use open for an empty draft or prefill supplied buyer, tax ID and line items. The demo declares {"mode":"draft"} in chat-card.json to support follow-up edits.
打开一张发票草稿。购方云杉科技,税号 DEMO123456,云服务 2 项,每项 120 元。
Open the draft and check the ¥240 total. Then enter “税号改为 DEMO987654” and verify that the buyer and line item remain.
App configuration
{
"name": "Invoice Draft",
"mode": "artifact",
"受众": "访客",
"客服工具": {
"version": 1,
"name": "visitor_invoice_draft",
"description": "Open or update an invoice draft. Pass supplied fields for the visitor to review and save.",
"parameters": {
"type": "object",
"properties": {
"intent": {
"type": "string",
"maxLength": 4,
"description": "Use new for a new draft and edit for the current draft.",
"enum": [
"new",
"edit"
]
},
"buyer": {
"type": "string",
"maxLength": 80,
"description": "Buyer name"
},
"taxId": {
"type": "string",
"maxLength": 30,
"description": "Tax ID"
},
"lines": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 80,
"description": "Line item"
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 9999
},
"price": {
"type": "number",
"minimum": 0.01,
"maximum": 999999
}
},
"required": [
"name"
],
"additionalProperties": false
}
}
},
"required": [
"intent"
],
"additionalProperties": false
},
"operation": {
"kind": "open"
}
}
}Read initial and updated fields
const { 参数: initial } = await aios.context()
if (initial) applyPrefill(initial)
aios.onSay((_message, details) => {
if (details?.参数) applyPrefill(details.参数)
})Connect the fragment to your own applyPrefill and only update supplied fields. Call the app’s authorized write action when the visitor chooses Save.
Verify and roll back
- Check matching and empty results, then combine a keyword and hall. Verify the filters and total on the card.
- Try blank, partial and complete prefill, then verify that a follow-up preserves unchanged fields.
- Turn off the protocol for the test role or remove the app from the role’s visible apps. Reload the visitor desk and verify the tool is unavailable.