Agent UI Mini Program SDK

AG-UI client SDK for WeChat Mini Programs.

Choose the Right Mini Program Integration

• Want a ready-to-use chat interface? → Use Agent UI Mini Program Component
• Want fully custom UI? → Use this SDK (@cloudbase/agent-ui-miniprogram)

Why Use This Library?

AG-UI is a protocol for building AI conversational applications. It defines how clients and servers communicate—streaming text, tool calls, message history, etc.

If you build an AG-UI client from scratch, you need to:

1. Parse Server-Sent Events streams from the server
2. Handle 15+ event types (TEXT_MESSAGE_START, TOOL_CALL_ARGS, RUN_ERROR...)
3. Maintain message state, merge streaming fragments, track tool call status
4. Execute client-side tools and send results back
5. Keep UI synchronized with all state changes

@cloudbase/agent-ui-miniprogram handles all this for you. You just need to:

Call this.agui.sendMessage to send messages:

// chat.js
this.agui.sendMessage('Hello')

Render the injected uiMessages data as UI:

<!-- chat.wxml -->
<view wx:for="{{agui.uiMessages}}" wx:key="id">
  {{item.role}}: {{item.parts[0].text}}
</view>

---

Installation

npm install @cloudbase/agent-ui-miniprogram@beta

---

Quick Start

import { createAGUIBehavior, CloudbaseTransport } from '@cloudbase/agent-ui-miniprogram'

Component({
  behaviors: [
    createAGUIBehavior({
      transport: new CloudbaseTransport({ botId: 'your-bot-id' }),
    })
  ],

  methods: {
    onSend(e) {
      this.agui.sendMessage(e.detail.value)
    }
  }
})

<view class="chat">
  <view wx:for="{{agui.uiMessages}}" wx:key="id" class="message {{item.role}}">
    <block wx:for="{{item.parts}}" wx:for-item="part" wx:key="id">
      <text wx:if="{{part.type === 'text'}}">{{part.text}}</text>
      <view wx:if="{{part.type === 'tool'}}" class="tool">
        🔧 {{part.name}}: {{part.status}}
      </view>
    </block>
  </view>
  <view wx:if="{{agui.error}}" class="error">{{agui.error.message}}</view>
</view>

<input placeholder="Type a message..." bindconfirm="onSend" disabled="{{agui.isRunning}}" />

---

Core Concepts

This SDK uses WeChat Mini Program's Behavior mechanism—a mixin pattern for reusing code across multiple components.

When you add the Behavior created by createAGUIBehavior() to a component, it will:

1. Inject AG-UI related state into this.data.agui
2. Provide this.agui.xxx methods to access AG-UI capabilities

State

The Behavior provides the following data in this.data.agui:

Property	Purpose
uiMessages	Render chat interface
isRunning	Show loading state, disable input
error	Display error messages

For other data, see API Reference.

Transport

Mini Program SDK  <--transport-->  AG-UI Server  <-->  LLM

@cloudbase/agent-ui-miniprogram is transport-agnostic by design. It only handles AG-UI event streams, manages state, and provides interaction methods, without caring about backend communication.

The Transport layer handles backend communication. You can pass any Transport instance that conforms to the interface when creating the Behavior.

createAGUIBehavior({
  transport: new AnyTransport()
})

@cloudbase/agent-ui-miniprogram provides CloudbaseTransport for connecting to Cloudbase Cloud Development Agent.

createAGUIBehavior({
  transport: new CloudbaseTransport({ botId: '...' })
})

Custom Transport must implement this interface:

interface Transport {
  run(input: RunAgentInput): AsyncIterable<BaseEvent>
}

Client Tools

Client tools enable Agents to interact with the Mini Program environment.

Use Cases:

• Access device features (location, camera, storage)
• Read client data (user preferences, shopping cart)
• Trigger UI actions (navigation, dialogs, toasts)

Example:

createAGUIBehavior({
  transport,
  tools: [{
    name: 'get_location',
    description: 'Get user current location',
    parameters: { type: 'object', properties: {} },
    handler: async ({ args }) => {
      const res = await wx.getLocation()
      return JSON.stringify(res)
    }
  }]
})

When the Agent decides to call a tool, the SDK executes your handler and automatically sends the result back to the Agent.

---

CloudbaseTransport Configuration

Transport implementation for WeChat Cloud Development (Cloudbase), based on wx.cloud.extend.AI.bot.

Prerequisites

1. Enable WeChat Cloud Development - Enable cloud development in your Mini Program
2. Create an Agent - Create an AI Bot and get its agentId

Configuration Steps

1. Initialize Cloud Development in app.js

// app.js
App({
  onLaunch() {
    wx.cloud.init({
      env: 'your-env-id'
    })
  }
})

2. Use CloudbaseTransport

import { createAGUIBehavior, CloudbaseTransport } from '@cloudbase/agent-ui-miniprogram'

const transport = new CloudbaseTransport({
  botId: 'your-agent-id'  // Get from Cloud Development Console
})

Component({
  behaviors: [createAGUIBehavior({ transport })]
})

CloudbaseTransport Constructor

new CloudbaseTransport(options: { botId: string })

Option	Type	Required	Description
botId	string	Yes	Agent ID from Cloud Development Console

How It Works

CloudbaseTransport internally calls wx.cloud.extend.AI.bot.sendMessage():

const res = await wx.cloud.extend.AI.bot.sendMessage({
  botId: 'your-bot-id',
  data: {
    threadId: '...',
    messages: [...],
    tools: [...],
    context: [...]
  }
})

for await (const event of res.eventStream) {
  // AG-UI events are streamed here
}

---

API Reference

createAGUIBehavior(options?)

Creates a Behavior mixin with AG-UI state management.

import { createAGUIBehavior } from '@cloudbase/agent-ui-miniprogram'

Component({
  behaviors: [createAGUIBehavior(options)]
})

Options

Option	Type	Description
transport	Transport	Transport implementation (required for sendMessage)
threadId	string	Conversation thread ID (auto-generated if not provided)
messages	Message[]	Initial messages
tools	ClientTool[]	Client tools with handlers
contexts	Context[]	Contexts for Agent runtime
onRawEvent	(event: BaseEvent) => void	Callback for each raw AG-UI event

Instance Methods

Access via this.agui.xxx after component is attached.

Method	Signature	Description
init	(config: AGUIConfig) => void	Initialize or reinitialize transport/threadId
sendMessage	(input: string \| Message[]) => Promise<void>	Send message and run agent
appendMessage	(message: Message) => void	Add message without triggering agent
setMessages	(messages: Message[]) => void	Replace entire message history
reset	() => void	Reset to initial state from options
setThreadId	(threadId: string) => void	Change thread ID
addTool	(tool: ClientTool) => void	Register new tool
removeTool	(name: string) => void	Remove tool by name
updateTool	(name: string, updates: Partial<ClientTool>) => void	Update tool properties
clearTools	() => void	Remove all tools

State Properties

Access via this.data.agui.xxx (use {{agui.xxx}} in WXML).

Property	Type	Description
messages	Message[]	Raw message history (for AI)
uiMessages	UIMessage[]	UI-optimized messages (for rendering)
isRunning	boolean	Whether Agent is processing
error	AGUIClientError \| null	Current error (if any)
activeToolCalls	ToolCallState[]	In-progress tool calls
threadId	string	Current conversation thread ID
tools	Tool[]	Registered tool definitions (without handlers)
contexts	Context[]	Registered contexts
runId	string \| null	Current run ID (null when not running)

this.agui Full Type

All data and methods are accessible via this.agui.

interface AGUINamespace {
  // Methods
  init(config: AGUIConfig): void
  sendMessage(input: string | Message[]): Promise<void>
  appendMessage(message: Message): void
  setMessages(messages: Message[]): void
  reset(): void
  setThreadId(threadId: string): void
  addTool(tool: ClientTool): void
  removeTool(name: string): void
  updateTool(name: string, updates: Partial<ClientTool>): void
  clearTools(): void

  // State (readonly, synced with this.data.agui)
  readonly messages: Message[]
  readonly uiMessages: UIMessage[]
  readonly isRunning: boolean
  readonly error: AGUIClientError | null
  readonly activeToolCalls: ToolCallState[]
  readonly threadId: string
  readonly tools: Tool[]
  readonly contexts: Context[]
  readonly runId: string | null

  // Config (readonly, original options passed to createAGUIBehavior)
  readonly config: CreateAGUIBehaviorOptions
}

Type Definitions

AG-UI Protocol Types

The following types are from the AG-UI Protocol. This SDK targets version: v0.0.42

For detailed definitions, refer to the AG-UI official documentation:

• Message - Message structure
• Tool - Tool definition
• ToolCall - Tool call structure
• Context - Agent context
• RunAgentInput - Agent run input
• BaseEvent - Event base structure
• EventType - Event type enum

UIMessage

interface UIMessage {
  id: string
  role: 'user' | 'assistant' | 'system' | 'developer'
  parts: UIMessagePart[]
}

type UIMessagePart = TextPart | ToolPart

interface TextPart {
  id: string
  type: 'text'
  text: string
  state?: 'streaming' | 'done'
}

interface ToolPart {
  id: string
  type: 'tool'
  toolCallId: string
  name: string
  argsString: string
  args: Record<string, unknown>
  status: 'pending' | 'ready' | 'executing' | 'completed' | 'failed'
  result?: unknown
  error?: AGUIClientError
}

ClientTool

Extends AG-UI's Tool type with a handler function for executing client tools.

interface ClientTool extends Tool {
  handler: (params: ToolHandlerParams) => string | Promise<string>
}

interface ToolHandlerParams {
  name: string
  description: string
  toolCallId: string
  args: Record<string, unknown>
}

AGUIClientError

interface AGUIClientError {
  code: AGUIClientErrorCode
  message: string
  recoverable: boolean
  details?: unknown
  originalError?: Error
}

type AGUIClientErrorCode =
  | 'INIT_ERROR'
  | 'TRANSPORT_ERROR'
  | 'RUNTIME_ERROR'
  | 'INVALID_EVENT'
  | 'TOOL_EXECUTION_ERROR'
  | 'TOOL_NOT_FOUND'
  | 'PARSE_ERROR'
  | 'TIMEOUT'
  | 'INVALID_CONFIG'
  | 'UNKNOWN'

ToolCallState

interface ToolCallState {
  toolCallId: string
  name: string
  argsString: string                    // Raw argument string (during streaming)
  args: Record<string, unknown>         // Parsed arguments
  status: ToolCallStatus
  result?: unknown
  error?: AGUIClientError
}

type ToolCallStatus = 'pending' | 'ready' | 'executing' | 'completed' | 'failed'

AGUIConfig

interface AGUIConfig {
  transport: Transport
  threadId?: string
}

CreateAGUIBehaviorOptions

interface CreateAGUIBehaviorOptions {
  transport?: Transport
  threadId?: string
  messages?: Message[]
  tools?: ClientTool[]
  contexts?: Context[]
  onRawEvent?: (event: BaseEvent) => void
}

Transport

interface Transport {
  run(input: RunAgentInput): AsyncIterable<BaseEvent>
}

See AG-UI Protocol Types for RunAgentInput and BaseEvent type definitions.

---