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.

  1. Prepare a visitor-facing artifact app and add it to a dedicated test role’s visible apps.
  2. 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.
  3. 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.

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.

Try in the Chinese demo

打开一张发票草稿。购方云杉科技,税号 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
JSON
{
  "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
JavaScript
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.