A2A Multi-Agent Collaboration

A2A makes Device Agents discoverable and callable by other agents. In the A2A workspace, you can save a repeatable Scene or send a one-off Task to coordinate several agents and devices.

Use A2A when:

• Another agent needs to call this Device Agent's commands.
• Several Device Agents need to complete one goal together.
• An external A2A client needs to discover and reuse device capabilities.

For direct conversation, debugging, or control of one device, use the Device Agent chat, MQTT, or SDK instead.

Before You Start

Check the following:

1. The Gateway can connect to an EMQX deployment with the A2A registry enabled. EMQX 6.2.0 or later is required.
2. Each participating Device Agent has at least one commands entry. Commands become callable skills.
3. Participating agents use the same MQTT broker, A2A organization, and A2A unit.
4. The Gateway has a usable LLM configured. See LLM Configuration.
5. Any devices needed during execution are online.

Runtime configuration provides the shared A2A identity:

Setting	Purpose	Default
A2A_ORG_ID	Organization used for registration and discovery	default
A2A_UNIT_ID	Unit used for registration and discovery	default
MQTT broker settings	Communication address in the agent card	Current MQTT runtime settings

See Configuration for configuration details.

Enable a Device Agent for A2A

1. Create a Device Agent, or open an existing Device Agent for editing.
2. Review the device specification in the preview panel.
3. Turn on Enable A2A Collaboration.
4. To also register the card in the shared registry, turn on Publish A2A Card.
5. Save the Device Agent.

The two options have different effects:

• Enable A2A Collaboration publishes the agent to the live A2A network. While the Gateway is connected, the agent can appear in the A2A workspace and receive requests.
• Publish A2A Card also adds the card to the A2A registry. Use it when the card needs a registered entry in addition to live discovery.

Turning off Enable A2A Collaboration and saving unpublishes the agent and removes its registered card.

Choose Scenes or Tasks

Open A2A and choose a mode at the top of the conversation:

Need	Mode
Save and reuse a generated collaboration workflow	Scenes
Complete a one-off request	Tasks

In Scenes, the left panel lists saved scenes and the right panel shows the selected scene's workflow. In Tasks, the left panel lists available agents, their skills, and online state.

All ready scenes share the center conversation. Selecting a scene opens its workflow for review, but does not bind the conversation to that scene. When you want to run a scene, name it or describe it unambiguously and explicitly ask the system to execute it.

Create a Reusable Scene

A scene saves a goal and a generated collaboration workflow. This example uses Humidifier, Smart Fan, and Smart Lock from the A2A list:

1. Open A2A and select Scenes.
2. Click the + button beside the scene list.
3. Enter the scene name and goal shown below.
4. Select all three A2A agents.
5. Click Create.

Field	Value
Scene name	Away Mode
Goal	Lock the door before leaving, and turn off the fan and humidifier
A2A agents	Humidifier, Smart Fan, and Smart Lock

Device Agent splits the goal into operations based on the three agents' skills and generates a collaboration flow. If required information is missing, it asks for that information before generation continues.

Follow Generation Status

After creation, the scene moves through these states:

State	What to do
Generating	Wait while the system prepares, plans, and validates the workflow.
Needs input	Open the scene, provide the requested information, then click Submit answer.
Ready	Review the workflow and run the scene from the shared conversation.
Failed	Review the reason. Edit the goal or agents, then save and regenerate the scene.
Updating	Wait while an edited scene is regenerated.

Review or Change a Scene

Select a scene in the left panel to open its workflow.

• Each node shows the assigned agent and its instruction.
• Connections summarize the planned flow. At run time, independent steps can run in parallel.
• Use the expand control to inspect a larger graph.
• For a ready or failed scene, click Edit to change its name, goal, or agents. Click Save & regenerate to rebuild the workflow.
• To remove a scene, use Delete in the scene list. Deletion is permanent.

Run a Scene

When Away Mode is ready, enter this in the A2A → Scenes conversation:

I'm heading out

Device Agent matches Away Mode; if several scenes fit, it asks which one to use. After you choose the devices for this run, it executes the collaboration flow and shows each step's status and the final result.

The stop control ends orchestration waiting and prevents steps that have not been dispatched. It cannot undo an action already sent to an agent or device, so check device state afterward when needed. Clearing the conversation also clears selected devices, but does not delete any scene.

Write Goals That Run Reliably

• State the desired outcome, not only the first action.
• Include thresholds, locations, and other fixed values.
• Say what final report or confirmation you expect.
• Select agents that can obtain every required live value.

Do not rely on values observed while a scene is being created. Current temperature, time, device state, and similar values must be read by an agent when the scene runs.

Run a One-Off Task

When several agents need to work together now but the flow is not worth saving as a scene, open A2A → Tasks and enter:

Getting ready for bed — make the house safe, quiet, and comfortable.

You do not need to choose devices in advance or break the goal into commands. When devices are preselected, Task Agent prefers their online agents when the capabilities fit. Otherwise, it plans the participants, steps, parameters, and execution order from the skills published by online agents.

When the plan needs a specific device, the page asks you to choose one and validates its availability; you can also preselect devices with the button beside the input. The execution trace shows the steps, statuses, and final result. Tasks are not saved as scenes, so each new run is planned from the currently online capabilities and the device choices for that run.

Verify Registry Publication

If Publish A2A Card is enabled, open EMQX Dashboard and confirm that the registered card is present and online.

The generated card includes the Device Agent name, description, MQTT interface, and one skill for each command in the device specification. Treat the A2A agent identifier as an opaque value and read it from discovery data or the registry instead of assembling it manually.

Saved A2A-enabled Device Agents are announced again after the Gateway restarts.

Connect an External A2A Client

External clients use MQTT v5 discovery and request/reply messages. See API Reference: A2A over MQTT for topics, the SendMessage request body, reply states, and device targeting.

For creating or running Scenes and one-off Tasks from a business system over HTTP, see API Reference: Multi-Agent Orchestration.

Persistence and Limits

• Scene definitions persist across Gateway restarts.
• A scene that was generating or updating during a restart is marked as failed. Edit and regenerate it after the Gateway is available.
• An in-progress scene or task stops when the Gateway restarts. Pending device selection must also be started again.
• Conversation history exists only in the current page session. Refreshing the page or switching between Scenes and Tasks clears it.
• Agents and selected devices must be online when their steps run.

Troubleshooting

Symptom	What to check
The agent does not appear in A2A > Tasks	Confirm that Enable A2A Collaboration was enabled before saving. Confirm that the Gateway is running and connected to the MQTT broker, then refresh the agent list.
Publishing fails because at least one command is required	Add at least one commands entry to the device specification, then save again.
The agent is listed as offline or agents cannot discover one another	Confirm that the Gateway is running and all agents use the same broker, A2A_ORG_ID, and A2A_UNIT_ID.
Device selection cannot continue	Select one online device for every listed agent. Replace stale or offline selections.