Turn business data and AI agent output into interactive cards in DingTalk.
An A2UI-based interface layer for business applications and AI agents. Compose interactive cards with declarative JSON and bring them to DingTalk across six platforms.
Gallery · Showcase · Templates · Capabilities · Quick start · Integration paths · Reference · Contributing
Generate A2UI directly from your application, or use a Skill to assist an agent. Query contracts and validate files with the standalone Python tools or native DWS commands; use DWS to preview, send, and update cards.
A showcase assembled from real DingTalk client screenshots. These examples illustrate the component system; for complete business scenarios, see the built-in templates. Watch component interactions.
47 components · 40 functions for layouts, content, inputs, expressions, and interactions. Explore the capabilities.
Collect user input, lock submitted controls, and let your application or agent continue the workflow.
Watch full recordings
- Live execution
- Expand and collapse
- End-to-end report
- Human-in-the-loop workflow
- Component interactions
The recordings use sample data and simulated tasks. GIFs focus on the card, are edited for pace, and play independently; videos are cropped and muted.
Start from one of nine complete business scenarios instead of a blank card: company information, morning briefing, today's tasks, approval summary, interview feedback, meeting invitation, meeting summary, task delegation, and weekly work report. Each scenario includes editable A2UI JSON and a rendered screenshot; approval summary also has a single-list JSON variant.
 Approval summary Approve or reject pending requests |
 Meeting invitation Collect the topic, participants, and agenda |
 Weekly work report Present results, plans, and risks |
 Task delegation Choose tasks to hand to an assistant |
Templates are starting points: replace the sample data and identifiers, connect actions to your service, and verify layout and interactions on your target clients. Screenshots show the initial state in a light-theme PC Web SDK preview, not a native client.
| Path | Best for | How it works |
|---|---|---|
| Business application | Existing services, templates, and business workflows | Generate A2UI in code, validate it, and deliver through a supported DingTalk integration or DWS. No Skill required. |
| Standalone Skill | Adding card authoring to your own agent | Install the Skill; the agent uses bundled guidance, protocol references, and Python lookup and validation tools. DWS is optional. |
| DWS integration | Native CLI tooling and DingTalk delivery | Call DWS directly from a program or terminal, or let an agent use the DWS-adapted Skill. No Python required. |
The two Skills share authoring guidance and protocol references, but use different execution tools. A Skill guides the agent; it is not a generation service. DWS commands work without a Skill, and copying a Skill does not add native commands to an older DWS binary.
An A2UI file is an ordered array of messages describing a Surface, its data, and its components. Start from a built-in template that matches your scenario, or from a complete report or form example, then replace demonstration data with your own.
Generate the file in application code, write it directly, or ask an agent to author it. Initialize a new card explicitly; send only intended changes when updating an existing card. See the Surface lifecycle.
Download or clone this repository into a writable directory outside /tmp and /private/tmp, then open a terminal at the repository root. Use Python 3.10+ with venv and ensurepip available:
python3 skills/dingtalk-aicard/scripts/setup_env.pyThe script creates or reuses .aicard-venv in the current directory and runs a self-check. Continue only when it exits successfully and reports ready: true. Initial setup may download dependencies; subsequent lookup and validation are offline. No DWS installation or DingTalk login is required.
Use the returned pythonExecutable for the commands below. With the default environment location, the POSIX-shell commands are:
.aicard-venv/bin/python skills/dingtalk-aicard/scripts/aicard_lint.py --explain Table --format json
.aicard-venv/bin/python skills/dingtalk-aicard/scripts/aicard_lint.py spec/examples/data-report.json --preflight new-card --format jsonOn Windows, use .aicard-venv\\Scripts\\python.exe instead. If you selected a custom environment with --venv, use its returned interpreter path.
A passing new-card check exits with code 0 and includes these fields:
{
"valid": true,
"preflight": {
"valid": true,
"diagnostics": []
},
"renderingVerified": false
}This is an excerpt, not the complete report. Review any diagnostics. You now have a locally validated example; replace the example path with your own A2UI file to repeat the check. Validation does not send a card.
The public DWS 1.0.65 release includes the native dws aicard explain, lint, and preview commands. dws aicard template is not yet in a public release and requires a DWS build containing this repository's current AICard module. Each release follows the protocol bundled with it, so check dws aicard --help and the selected leaf's help.
If they are unavailable, continue with the Python path above. Developers integrating the native module can follow the source-build instructions. Installing or copying the DWS Skill alone does not install the native commands.
With a compatible build:
dws aicard explain Table --format json
dws aicard lint --file spec/examples/data-report.json --preflight new-card --format json
dws aicard preview --file spec/examples/data-report.json --dry-run --format jsonNative lookup and validation need neither Python nor a signed-in Profile. DWS wraps successful validation results in data: check data.valid and data.preflight.valid. Preview with --dry-run stays local.
Delivery is separate from the offline quick start. Use DingTalk Workspace CLI or your supported delivery integration. Follow its authentication instructions, select the intended organization and account, and resolve the target before sending.
DWS's general chat commands are separate from the native AICard module: inspect dws chat message send-a2ui-card --help and dws chat message update-a2ui-card --help in your installed CLI. Their availability does not imply that dws aicard is installed.
With the native module, dws aicard preview --file spec/examples/data-report.json --format json sends a real self-preview. Use native lint --emit when serialized messages are needed; JSON-encode data.a2uiMessages as the sending command's --content argument. Without the module, serialize each validated A2UI message to a string and JSON-encode the resulting string array using a program.
Preserve the server-returned bizId and the original surfaceId for updates. Complete a static native preview through an update using --flow-status FINISH and a nonempty, state-preserving delta; do not replay creation or reset form values. See the DWS delivery guidance.
Standalone: copy the complete skills/dingtalk-aicard/ directory into your agent's supported skills directory. Keep references, scripts, and license files together. Follow its Python setup instructions; the repository root and DWS are not required after installation.
DWS: use the DWS-adapted Skill with a compatible DWS build. It guides the agent through native lookup, validation, and requested delivery rather than invoking Python scripts.
For example:
Create an A2UI expense-review card with a summary, an itemized table, and an editable reviewer note. Use labeled sample data, leave unspecified business actions unconnected, and validate the file. Do not send it.
The native dws aicard rows require the compatible build described above. The dws chat message rows belong to the separate chat delivery API; check availability in your installed CLI.
| Task | Command | Result |
|---|---|---|
| Inspect contracts | dws aicard explain <name> |
Component, function, common-type, or Token definitions; supports batch lookup |
| Validate JSON | dws aicard lint --file <file> |
Schema validation and field-level diagnostics |
| Check new-card structure | lint --preflight new-card |
Initialization, root, static references, and cycle checks |
| Check media resources | lint --preflight resources |
Reject literal data: resource fields; flag Markdown markers for review |
| Serialize for delivery | lint --emit |
Validated messages as a string array in data.a2uiMessages |
| Preview to yourself | dws aicard preview --file <file> |
A real self-preview; --dry-run stays local |
| Create a cloud template | dws aicard template create --file <file> |
Save a complete A2UI file; return its new ID and assigned version |
| Retrieve a template | dws aicard template get --template-id <ID> --version <version> --out <new-file> |
Save retrieved content and return its digest; actual version remains unconfirmed |
| Revise a template | dws aicard template update --template-id <ID> --file <file> |
Append a version under the same ID; does not activate it or change sent cards |
| Send to a target | dws chat message send-a2ui-card |
Create and send to the selected person or conversation |
| Update a card | dws chat message update-a2ui-card |
Update the original card using its server-issued bizId |
The lint rows abbreviate dws aicard lint --file <file> plus the listed option. See command help for fragment validation, package self-checks, compact queries, and delivery parameters. Lookup and validation are local; template operations, actual preview, sending, and updating require authentication and service access.
Template commands manage assets independently of card delivery. They accept complete UTF-8 A2UI files up to 768 KiB, preserve inline or explicit initialization, and use the current Profile's published MCP access. Configure the intended environment's service explicitly with --mcp-id or DWS_AICARD_TEMPLATE_MCP_ID; there is no cross-environment default, including for dry-run. get requires a new output path and refuses overwrites. The service may return latest content when a requested version is absent; compare data.templateDigest with the approved business binding and do not treat requestedVersion as confirmed. Business configuration owns scene bindings, version activation, and rollback. Template files may include a leading UTF-8 BOM; it is removed before validation, hashing, and transmission. Template writes have no automatic retry; template dry-runs neither call the service nor write files.
Before using the generated DWS Skill for delivery, verify that the installed chat message send-a2ui-card help exposes --summary and --support-forward. Integrate the compatible chat changes before distributing the Skill; copying the AICard module does not add flags to an older chat implementation. The installer and native integration tests check this dependency.
Both tool paths check syntax and protocol constraints, including fields, required values, types, and enumerations. Diagnostics identify the failing field so a developer or agent can repair the original payload.
New-card preflight additionally checks initialization and the final static component snapshot; resource preflight rejects literal data: values in resource fields as workflow policy. Markdown and fallbackMarkdown containing data: text produce nonblocking review warnings; no Markdown/HTML parsing is performed. Review image destinations before delivery and prefer verified HTTPS assets. Check the selected preflight result as well as Schema validity. These checks do not evaluate bindings or functions, certify every streaming frame, load remote media, or prove client rendering and callbacks. Verify actual behavior in the target client.
The current V0.8 protocol defines 47 components and 40 functions: 14 core functions, 18 expression functions, 7 DingTalk host actions, and the system function @index defined in the common types. These counts describe protocol definitions, not the number of examples.
| Capability | Included examples |
|---|---|
| Layout and composition | Row, Column, GridLayout, Stack, Tabs, CollapsiblePanel, Loop |
| Content and data | Text, Markdown, Table, Chart, File, ProgressBar |
| Inputs and selection | TextField, NumberInput, ChoicePicker, DateTimeInput, UserPicker, ImageUpload |
| Media | Image, ImageCarousel, Video, AudioPlayer |
| Expressions | Arithmetic (add, mul), comparison (eq, gt), conditionals (cond), array and object access (arrayGet, objectGet) |
| Functions | Formatting (formatDate, formatNumber), validation (required, regex), logic (and, or, not) |
| Host actions | copyText, openChat, previewImages, previewVideo, promptText, showConfirm, showModal |
| Events and callbacks | action.event for named application events; action.functionCall for renderer-side functions; component-specific slots such as onTap, onComplete, and onPreview |
| Data and updates | Path bindings, data-driven lists, updateDataModel, and updateComponents |
View all 47 component names
- Common components:
Button,Card,Column,Divider,Icon,Image,Markdown,Row,Tag,Text. - Composition:
ButtonGroup,CardHeader,CollapsiblePanel,ColumnLayout,GridLayout,Link,List,Loop,ScrollView,Stack,Tabs. - Inputs:
CheckBox,CheckableImageList,CheckboxListMulti,ChoicePicker,ConversationPicker,DateTimeInput,ImageUpload,InputList,NumberInput,Rating,Slider,Switch,TextField,UserPicker. - Data and media:
AudioPlayer,Avatar,AvatarGroup,Chart,Countdown,ElapsedTime,File,ImageCarousel,ImageList,ProgressBar,Table,Video.
Browse the component contracts, function contracts, and action schema. Event slots and function placement are defined per component; the table does not imply every action is accepted in every slot.
flowchart LR
Business[Business application] -->|Generate| JSON[A2UI messages]
Skill[Standalone or DWS Skill] -.->|Guide| Agent[AI agent]
Agent -->|Generate| JSON
JSON --> Check[Python or DWS validation]
Check --> Delivery[DWS or supported delivery integration]
Delivery --> Client[DingTalk: six platforms]
Client -->|Business events via integration| Handler[Application or agent]
Handler -->|Incremental updates| JSON
The application or agent produces A2UI; the tools inspect and validate it; the delivery integration sends it; DingTalk renders the card and handles client interactions. Your integration handles business events and subsequent updates. This repository does not bundle client renderer source or an automatic business orchestration service.
For live execution, send successive complete message batches as work progresses. Submitting an entire recorded sequence at once may expose only the final state. See execution and replay guidance.
| Resource | What to find |
|---|---|
| Specification | Messages, data binding, expressions, lifecycle, and compatibility |
| Components | Layouts, display, input, and interaction components |
| Functions | Function contracts and host actions |
| Visual Tokens | Colors, typography, and icon references |
| Form and event example · Host actions | Input bindings and interaction message shapes |
| Scenario examples | Complete A2UI examples to adapt |
| Standalone Skill · DWS Skill | Authoring workflows and execution-specific instructions |
| DWS build and integration | Native module integration and reproducible builds |
README media lives in assets/showcase/, separate from protocol examples and installed Skills.
DingTalk AI Card's published components, functions, expressions, events, and visual effects are supported across iOS, Android, HarmonyOS, Windows, macOS, and Web, including shimmer and generation indicators. Layout adapts to each platform's screen size and host interface.
V0.8 is the DingTalk specification release; message version remains "v1.0". The specification is based on A2UI 1.0 with DingTalk extensions and a supported subset, not a drop-in implementation for every A2UI renderer. See compatibility and terms.
See CONTRIBUTING.md for source ownership, builds, and tests. For rendering issues, include the client platform/version, a minimal sanitized payload, and expected versus observed behavior. Never post credentials or private user data. Report vulnerabilities through the private channels in SECURITY.md.
Apache-2.0. See NOTICE for attribution and scope, and spec/NOTICE for protocol provenance. Both Skill distributions include license and notice files for redistribution.