Invoke an Agent

Send a message to a remote Agent2Agent (A2A) agent from a Maestro agentic process and use the agent's response in later process steps.

Description

This activity sends a message to a remote A2A agent and returns the agent's response, so the agent can take part in a process orchestrated by Maestro.

The agent answers in one of two ways:

• Immediate reply: the agent returns a message, and the task completes with that message.
• Long-running task: the agent returns a task. Integration Service polls the agent for the task status, and the task completes when the agent task reaches a final state. For details, refer to Agent 2 Agent events.

Prerequisites

• An Agent 2 Agent connection to the agent you want to call. For details, refer to Agent 2 Agent authentication.
• The agent meets the remote agent requirements.

Adding the activity to a Maestro process

1. Add a service task element to the canvas and open the task's Properties panel.
2. In the Implementation section, from the Action dropdown list, select Start and wait for external agent.
3. Select the Agent 2 Agent connector.
4. Select an existing connection or create a new one.
5. From Activity, select Invoke an Agent.
6. From Agent Skills, select the skill to use.
7. In Message content, enter the message to send to the agent.

At runtime, Maestro sends the message to the agent and waits for the response before moving to the next step.

Configuration

Field	Direction	Description
Connection	Input	The connection established in Integration Service. Access the dropdown menu to choose, add, or manage connections.
Agent Skills	Input	Required. A skill from the Agent Card of the agent. Selecting a skill shows its description, examples, and parameters, to help you write the message.
Message content	Input	Required. The text of the message sent to the agent.
Role	Input	Optional. The role of the message sender, for example user.
Context identifier	Input and output	Optional. The ID of an existing conversation context. Enter the Context identifier output of an earlier Invoke an Agent task to continue that conversation.
Blocking	Input	Optional. Whether to ask the agent for a synchronous reply instead of a long-running task.
Accepted output modes	Input	Optional. The response formats you accept, for example text.
History length	Input	Optional. The number of previous messages to include in the context.
Metadata	Input and output	Optional. Key-value pairs for additional context or tracking information.
Current status state	Output	The final state of the agent task, for a long-running task.
Status error	Output	Error information, if the agent task failed.
Artifacts	Output	The results produced by the agent task. Each artifact has an identifier, a name, and parts. The Artifact part text field holds the text of each part.
History	Output	The messages exchanged in the task, with their role and text.

Using the agent's response in the process

To let the agent's response influence the process, for example to make a decision at a gateway, assign it to a process variable.

1. In Design mode, select the service task on the canvas.
2. Select Properties.
3. Under Output, select Add new.
4. Add a variable of type String, for example agent_response.
5. For Value, select the field that holds the agent's answer from the task's response. For a long-running task, this is usually the Artifact part text field.

Tip:

When a later step needs structured data, ask the agent to respond only with a JSON object, then parse the response in Maestro.