This module provides the server implementation capabilities of the Agent to Agent (A2A) protocol, including creating A2A server instances, processing client requests, and managing task status and artifacts (products generated by agents during task execution).
The A2A protocol is used for communication between agents. The A2A server is responsible for receiving client requests, triggering agents to execute tasks, updating task statuses, and returning execution results.
Since: 26.0.0
Modules to Import
import { Role, TaskState, Part, Message, Artifact, TaskStatus, Task, OnDataCallback, createA2AServer, ProxySender,
Server, RequestContext, TaskArtifactParam } from '@kit.AgentFrameworkKit'; createA2AServer
createA2AServer(agentCard: common.AgentCard, onData: OnDataCallback, want?: Want): Server
Creates and obtains an A2A server instance to handle A2A protocol communications. After this method is called, an A2A server instance is created and ready to start.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| agentCard | common.AgentCard | Yes | AgentCard information. |
| onData | OnDataCallback | Yes | Callback function for agent data processing. |
| want | Want | No | Want object that contains the A2A version information. |
Returns:
| Type | Description |
|---|---|
| Server | Created A2A server instance. This server instance can be used to call methods such as start(), stop(), and onMessage() to control the A2A server's behavior. |
Error codes:
For details about the error codes, please refer to ArkTS API Error Codes.
| ID | Error Message |
|---|---|
| 1022400010 | Invalid parameter |
| 1022420001 | Memory allocation failed |
Example:
import { Want, AgentExtensionAbility } from '@kit.AbilityKit';
import { createA2AServer, Server, RequestContext, OnDataCallback } from '@kit.AgentFrameworkKit';
export default class MyAgentExtensionAbility extends AgentExtensionAbility {
private server: Server | null = null;
private agentOnData: OnDataCallback = (method: string, context: RequestContext) => {
// Process the agent operation request from the client and execute the corresponding service logic based on the method type.
}
async onCreate(want: Want) {
try {
const card = this.context.agentCard;
this.server = createA2AServer(card, this.agentOnData, want);
} catch (error) {
console.error(`Failed to create server: ${error}`);
}
}
} OnDataCallback
type OnDataCallback = (method: string, context: RequestContext) => void
Event callback function that is triggered to execute the agent after the A2A server receives a request from the client.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| method | string | Yes | Agent operation type. The options are as follows: 'Execute': triggers the execution operation. It is triggered when Celia sends messages such as "Dialogue Interaction", "Long-Task Companionship", "UI Control Companionship", or "Native Control". In this case, the client uses either the SendMessage or SendStreamingMessage method. The agent should read the required information from context, update the task status via updateStatus, and return artifacts using addArtifact. The execution is considered complete once the status changes to a state other than WORKING or SUBMITTED. 'Cancel': triggers the cancellation operation. It is triggered when the client sends a "CancelTask" request. The agent then should attempt to stop the task specified in context. 'PerceptionSuggest': triggers the perception suggestion operation. It is used by Celia during initialization to retrieve perception suggestion chips from the agent. The agent should read the required information from context, update the task status via updateStatus, and return artifacts using addArtifact. The execution is considered complete once the status changes to a state other than WORKING or SUBMITTED. 'GetOpening': obtains the application opening greeting. It is used by Celia during initialization to obtain the opening greeting from the application's agent. Other A2A methods. |
| context | RequestContext | Yes | Request context object. |
ProxySender
type ProxySender = (data: string) => void
Callback function used to send the A2A response data to the client through a proxy.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data | string | Yes | Data to be sent to the client. |
Server
Server instance API responsible for handling agent communication and task lifecycle management.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
[h2]start
start(): void
Starts an A2A server instance.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Example:
// The server object is created using the createA2AServer API. server.start();
[h2]stop
stop(): void
Stops a server instance.
Before calling this API, call the start method to start the A2A server instance. Otherwise, this API will not take effect.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Example:
// The server object is created using the createA2AServer API. server.stop();
[h2]onMessage
onMessage(data: string, sender: ProxySender): void
Used by the A2A server to process message requests from the A2A client and send responses back to the client.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data | string | Yes | JSON string of the client request. |
| sender | ProxySender | Yes | Callback function used to send a response to the client. |
Example:
// The server object is created using the createA2AServer API.
// data is the request data of the client obtained through the transport layer.
// The proxy provides an externally defined message sending API.
server.onMessage(data, (response: string) => {
proxy.sendData(response);
}); [h2]onAuth
onAuth(data: string): string
Used by the A2A server to process key agreement requests from the A2A client.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| data | string | Yes | Key agreement request from the client, including the public key of the client. |
Returns:
| Type | Description |
|---|---|
| string | Key agreement information, including the public key of the server. |
Example:
// The server object is created using the createA2AServer API. // data is the authentication data of the client obtained through the transport layer. const authResp: string = server.onAuth(data);
[h2]updateStatus
updateStatus(taskId: string, status: TaskStatus): void
Update the task status.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| taskId | string | Yes | Unique ID of a task, which must be in UUID format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. |
| status | TaskStatus | Yes | New task status. |
Example:
// The server object is created using the createA2AServer API.
// taskId is the task ID obtained via the getTaskId API of RequestContext.
server.updateStatus(taskId, {
state: TaskState.COMPLETED,
message: {
messageId: 'msg1',
role: Role.AGENT,
parts: [{
text: 'Task completed'
}]
}
}); [h2]addArtifact
addArtifact(taskId: string, taskArtifactParam: TaskArtifactParam): void
Adds task agent artifact information.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| taskId | string | Yes | Unique ID of a task. |
| taskArtifactParam | TaskArtifactParam | Yes | Artifact update parameters. |
Example:
// The server object is created using the createA2AServer API.
// taskId is the task ID obtained via the getTaskId API of RequestContext.
server.addArtifact(taskId, {
artifactId: 'result-artifact-id',
parts: [{
mediaType: 'application/json',
data: {'action': 'completed', 'result': 'Task finished successfully'}
}]
}); RequestContext
Provides the context of the request.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
[h2]getAgentId
getAgentId(): string | undefined
Obtains the agent ID.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| string | undefined | Agent ID. If the agent ID does not exist, undefined is returned. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented. const agentId: string = context.getAgentId() ?? '';
[h2]getUserInput
getUserInput(delimiter?: string): string
Obtains user input.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Parameters:
| Name | Type | Mandatory | Description |
|---|---|---|---|
| delimiter | string | No | Separator used to separate multiple user inputs. |
Returns:
| Type | Description |
|---|---|
| string | User input. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented.
const userInput: string = context.getUserInput(','); [h2]getMessage
getMessage(): Message | undefined
Obtains the message body object from an A2A client request.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| Message | undefined | Message object. If the object does not exist, undefined is returned. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented. const message = context.getMessage();
[h2]getCurrentTask
getCurrentTask(): Task | undefined
Obtains the current task.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| Task | undefined | Current task object. If the object does not exist, undefined is returned. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented. const currentTask = context.getCurrentTask();
[h2]getTaskId
getTaskId(): string | undefined
Obtains the task ID.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| string | undefined | Task ID. If the task ID does not exist, undefined is returned. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented. const taskId: string = context.getTaskId() ?? '';
[h2]getContextId
getContextId(): string | undefined
Obtains the context ID.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| string | undefined | Context ID. If the context ID does not exist, undefined is returned. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented. const contextId: string = context.getContextId() ?? '';
[h2]getMetadata
getMetadata(): object
Obtains client request metadata, which is used to carry additional request information.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Returns:
| Type | Description |
|---|---|
| object | Metadata. |
Example:
// The context object is obtained as a parameter when the OnDataCallback API is implemented. const metadata: object = context.getMetadata();
TaskArtifactParam
Task artifact update parameter API.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| parts | Part[] | No | No | Array of artifact content parts. |
| artifactId | string | No | Yes | Unique ID of the artifact. |
| name | string | No | Yes | Artifact name. |
| metadata | object | No | Yes | Artifact metadata, which must support JSON serialization. |
| append | boolean | No | Yes | Indicates whether to append the current parts array to an existing artifact with the same ID in the task history. The value true indicates to append to the existing artifact with the same ID, and the value false indicates to add a new item to the artifact list. The default value is false. |
| lastChunk | boolean | No | Yes | Indicates whether the data chunk is the last one. The value true indicates yes, and the value false indicates no. The default value is false. |
| extensions | string[] | No | Yes | Extension URI list. |
TaskState
Enumerates the task statuses.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Value | Description |
|---|---|---|
| SUBMITTED | 0 | Task submitted. |
| WORKING | 1 | Task in progress. |
| INPUT_REQUIRED | 2 | User input required to continue the task. |
| COMPLETED | 3 | Task completed successfully. |
| CANCELED | 4 | Task canceled. |
| FAILED | 5 | Task failed. |
| REJECTED | 6 | Task rejected. |
| AUTH_REQUIRED | 7 | Authentication required to continue the task. |
| UNSPECIFIED | 8 | Unspecified. |
Role
Enumerates message sender roles.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Value | Description |
|---|---|---|
| AGENT | 0 | Agent. |
| USER | 1 | User. |
| UNSPECIFIED | 2 | Unspecified. |
Message
Message API, which represents a message unit in A2A communication.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| messageId | string | No | No | Unique ID of a message, in UUID format. |
| role | Role | No | No | Role of the message sender. |
| parts | Part[] | No | No | Array of message content parts. |
| contextId | string | No | Yes | Context ID, in UUID format. |
| extensions | string[] | No | Yes | Extension URI list. |
| metadata | object | No | Yes | Metadata, which must support JSON serialization. |
| referenceTaskIds | string[] | No | Yes | List of referenced task IDs. |
| taskId | string | No | Yes | Task ID, in UUID format. |
Part
Message content API, which supports text, raw data, URL, media and other types.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| text | string | No | Yes | Text content. |
| raw | string | No | Yes | Raw data. |
| url | string | No | Yes | URL pointing to file content, which must comply with standard URL specifications, such as file://, https://, and http://. |
| data | object | string | number | boolean | No | Yes | Any object, string, number, or boolean value that supports JSON serialization. |
| mediaType | string | No | Yes | Media type (MIME type) of the Part content, such as text/plain, application/json, or image/png. |
| filename | string | No | Yes | File name, for example, document.pdf. |
| metadata | object | No | Yes | Metadata, which must support JSON serialization. |
Task
Task API representing an A2A task, including the task status, artifacts, and historical messages.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| id | string | No | No | Unique ID of a task, in UUID format. |
| contextId | string | No | No | Context ID, in UUID format. |
| status | TaskStatus | No | No | Task status. |
| artifacts | Artifact[] | No | Yes | Task artifact list. |
| history | Message[] | No | Yes | List of historical messages. |
| metadata | object | No | Yes | Metadata, which must support JSON serialization. |
TaskStatus
Task status API representing the current status of a task.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
Artifact
Agent artifact API representing resources generated by a task.
Model restriction: This API can be used only in the stage model.
System capability: SystemCapability.AI.Agent.AgentKit
Since: 26.0.0
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| artifactId | string | No | No | Unique ID of an agent artifact, in UUID format. |
| parts | Part[] | No | No | Array of agent artifact content parts. The array must contain at least one part. |
| description | string | No | Yes | Description of the agent artifact. |
| extensions | string[] | No | Yes | Extension URI list. |
| metadata | object | No | Yes | Metadata, which must support JSON serialization. |
| name | string | No | Yes | Name of the agent artifact. |