Agent

The Agent task runs an agent from a workflow and returns its result. It supports two types of agents:

• A2A: A remote agent that supports the Agent2Agent (A2A) protocol. The task sends a message to the agent and waits for it to finish.
• Conductor: An agent deployed on your Conductor cluster.

The task finishes when the agent reaches a final state. If the agent needs input before it can continue, the task returns with the state input-required so that your workflow can respond.

Task parameters

Configure these parameters for the Agent task.

Parameter	Description	Required/ Optional
inputParameters.agentType	The type of agent to run. Supported values: a2a: A remote A2A agent. conductor: An agent deployed on Conductor. Defaults to a2a.	Optional.

A2A agent parameters

Use these parameters when agentType is a2a.

Parameter	Description	Required/ Optional
inputParameters.agentUrl	The URL of the remote agent. Use the agent's JSON-RPC endpoint. If the URL ends in .json, it is treated as an Agent Card URL, and the task uses the endpoint advertised in the card.	Required.
inputParameters.text	The message to send to the agent.	Required, unless parts or message is provided.
inputParameters.parts	A list of A2A message parts, for messages that are not plain text. For example, [{"kind": "text", "text": "Hello"}]. Takes precedence over text.	Optional.
inputParameters.message	A complete A2A message object. Takes precedence over parts and text.	Optional.
inputParameters.headers	A map of HTTP headers to send with every request to the agent, such as an Authorization header.	Optional.
inputParameters.contextId	The context ID of an earlier conversation, to continue it. Use the contextId from a previous Agent task output.	Optional.
inputParameters.taskId	The ID of an existing remote task, to continue it, for example to provide input after the agent returned input-required. Use the taskId from a previous Agent task output.	Optional.
inputParameters.historyLength	The number of past messages to request from the agent in its response.	Optional.
inputParameters.metadata	A map of extra metadata to attach to the message sent to the agent.	Optional.
inputParameters.streaming	Whether to receive the agent's response as a stream, instead of polling. The agent must support streaming. Defaults to false.	Optional.
inputParameters.pushNotification	Whether the agent should call back Conductor when the task finishes, instead of Conductor polling the agent. Requires the callback URL to be configured on your Conductor cluster. If it is not configured, the task polls the agent instead. Defaults to false.	Optional.
inputParameters.pushBackstopPollSeconds	How often, in seconds, to poll the agent as a fallback when pushNotification is true. Defaults to 300.	Optional.
inputParameters.pollIntervalSeconds	How often, in seconds, to poll the agent for the result. Defaults to 5.	Optional.
inputParameters.maxDurationSeconds	The maximum time, in seconds, to wait for the agent to finish. Defaults to 86400 (24 hours).	Optional.
inputParameters.maxPollFailures	The maximum number of failed polls in a row before the task fails. Defaults to 30.	Optional.

Conductor agent parameters

Use these parameters when agentType is conductor.

Parameter	Description	Required/ Optional
inputParameters.name	The name of the agent to run.	Required.
inputParameters.version	The version of the agent to run. Defaults to the latest version.	Optional.
inputParameters.prompt	The message to send to the agent.	Required, unless resuming with executionId.
inputParameters.model	Overrides the model the agent uses. Use the format <integration>/<model>, for example openai/gpt-4o.	Optional.
inputParameters.sessionId	Associates the run with a session, so that agent runs with the same session ID share a conversation. Returned as contextId in the output.	Optional.
inputParameters.context	A map of values passed to the agent as context.	Optional.
inputParameters.media	A list of URLs of images or other media to send to the agent with the prompt. The URLs must be publicly accessible. The agent's model must support the media type.	Optional.
inputParameters.executionId	The execution ID of a run that is waiting for input. Use it to respond to the run, instead of starting a new one. Set prompt to your response.	Optional.
inputParameters.pollIntervalSeconds	How often, in seconds, to poll the agent for the result. Defaults to 5.	Optional.
inputParameters.maxDurationSeconds	The maximum time, in seconds, to wait for the agent to finish. Defaults to 86400 (24 hours).	Optional.
inputParameters.maxPollFailures	The maximum number of failed polls in a row before the task fails. Defaults to 30.	Optional.

The following are generic configuration parameters that can be applied to the task and are not specific to the Agent task.

Caching parameters

You can cache the task outputs using the following parameters. Refer to Caching Task Outputs for a full guide.

Parameter	Description	Required/ Optional
cacheConfig.ttlInSecond	The time to live in seconds, which is the duration for the output to be cached.	Required if using cacheConfig.
cacheConfig.key	The cache key is a unique identifier for the cached output and must be constructed exclusively from the task’s input parameters. It can be a string concatenation that contains the task’s input keys, such as ${agentUrl}-${text} or re_${agentUrl}_${text}.	Required if using cacheConfig.

Other generic parameters

Here are other parameters for configuring the task behavior.

Parameter	Description	Required/ Optional
optional	Whether the task is optional. If set to true, any task failure is ignored, and the workflow continues with the task status updated to COMPLETED_WITH_ERRORS. However, the task must reach a terminal state. If the task remains incomplete, the workflow waits until it reaches a terminal state before proceeding.	Optional.

Task configuration

This is the task configuration for an Agent task.

A2A agentConductor agent

{
  "name": "agent",
  "taskReferenceName": "agent_ref",
  "type": "AGENT",
  "inputParameters": {
    "agentType": "a2a",
    "agentUrl": "<YOUR-AGENT-URL>",
    "text": "<YOUR-MESSAGE>"
  }
}

{
  "name": "agent",
  "taskReferenceName": "agent_ref",
  "type": "AGENT",
  "inputParameters": {
    "agentType": "conductor",
    "name": "<YOUR-AGENT-NAME>",
    "prompt": "<YOUR-PROMPT>"
  }
}

Task output

The Agent task will return the following parameters.

Parameter	Description
state	The state of the agent run, such as completed, failed, canceled, or input-required.
text	The text returned by the agent. If the run failed, the error message.
contextId	The ID of the conversation. Pass it as contextId (A2A) or sessionId (Conductor) in another Agent task to continue the conversation. For a Conductor agent, defaults to the execution ID if no sessionId was set.
taskId	The ID of the agent task. For a Conductor agent, this is the same as executionId.
artifacts	The artifacts produced by the agent, such as its result.
agentMessage	The final message from the agent. Not returned when streaming is true.
task	The full task object, including the status and message history.
a2aStartedAt	The time the task started, in epoch milliseconds. Returned for A2A agents.
a2aPollFailures	The number of failed polls in a row. Returned for A2A agents.
executionId	The ID of the agent run. Returned for Conductor agents. Use it as executionId to respond to a run that is waiting for input.
agentName	The name of the agent that ran. Returned for Conductor agents.
output	The result of the Conductor agent, as {"result": "<text>"}. Returned for Conductor agents when the run completes.
agentStartTime	The time the run started, in epoch milliseconds. Returned for Conductor agents.
agentEndTime	The time the run ended, in epoch milliseconds. Returned for Conductor agents when the run is finished.
agentPollFailures	The number of failed polls in a row. Returned for Conductor agents.
waiting	true when the agent run is waiting for input and state is input-required. Returned for Conductor agents.
pendingTool	Details of the request the agent is waiting on, including the taskRefName and the response_schema for the response. Returned for Conductor agents when waiting is true.

Examples

Here are some examples for using the Agent task.

Calling an A2A agent

{
  "name": "agent",
  "taskReferenceName": "currency_agent",
  "type": "AGENT",
  "inputParameters": {
    "agentType": "a2a",
    "agentUrl": "https://agents.example.com/a2a",
    "text": "convert 100 USD to EUR",
    "headers": {
      "Authorization": "Bearer ${workflow.secrets.agent_token}"
    }
  }
}

Continuing a conversation with an A2A agent

The second task passes the contextId and taskId from the first task's output.

[
  {
    "name": "agent",
    "taskReferenceName": "first_agent",
    "type": "AGENT",
    "inputParameters": {
      "agentUrl": "https://agents.example.com/a2a",
      "text": "convert 100 USD to EUR"
    }
  },
  {
    "name": "agent",
    "taskReferenceName": "second_agent",
    "type": "AGENT",
    "inputParameters": {
      "agentUrl": "https://agents.example.com/a2a",
      "text": "now convert 200 USD to EUR",
      "contextId": "${first_agent.output.contextId}",
      "taskId": "${first_agent.output.taskId}"
    }
  }
]

Running a Conductor agent

{
  "name": "agent",
  "taskReferenceName": "cat_agent",
  "type": "AGENT",
  "inputParameters": {
    "agentType": "conductor",
    "name": "catfact_agent",
    "prompt": "Tell me one fact.",
    "context": {
      "topic": "cats"
    }
  }
}

Related pages

• AI Tasks
• LLM Text Complete
• LLM Generate Embeddings
• LLM Store Embeddings
• LLM Get Embeddings
• LLM Search Embeddings