A2ATask

An A2ATask tracks a single unit of work executed by a remote agent over the Agent-to-Agent (A2A) protocol . Ark creates one automatically whenever a Query targets an agent backed by an A2AServer: the controller submits the task to the remote server, then polls it until the task reaches a terminal state, mirroring the remote agent’s progress into the A2ATask’s status.

The resource carries two independent lifecycles that this page documents separately:

status.phase — the Kubernetes lifecycle Ark manages (pending → running → completed / failed / …).
status.protocolState — the raw A2A protocol state reported by the remote agent (submitted, working, completed, …).

Ark derives phase from protocolState, but they are distinct enums with different values; read both when debugging a stuck task.

Spec


apiVersion: ark.mckinsey.com/v1alpha1
kind: A2ATask
metadata:
  name: task-weather-12345
  namespace: default
spec:
  # --- Required ----------------------------------------------------------
  queryRef:                       # originating Query
    name: weather-query
    namespace: default
  a2aServerRef:                   # A2AServer to poll for status updates
    name: langchain-agents
    namespace: default
  agentRef:                       # Agent assigned to execute the task
    name: weather-agent
    namespace: default
  taskId: "task-12345"            # A2A protocol task id (minLength 1)
 
  # --- Optional ----------------------------------------------------------
  contextId: "context-67890"      # A2A conversation context for stateful turns
  input: "What's the weather in New York today?"
  parameters:                     # extra key/value parameters for execution
    location: "New York"
    format: detailed
  priority: 0                     # higher values execute first; default 0
  timeout: 12h                    # polling timeout; default '12h'
  ttl: 720h                       # retention after completion; default '720h'
  pollInterval: 5s                # how often to poll the server; default '5s'

Fields

Field	Type	Required	Description
`spec.queryRef`	object (`{name, namespace}`)	yes	The `Query` that created this task. The Query’s `status.response.a2a.taskId` points back at this A2ATask. `name` is required; `namespace` defaults to the A2ATask’s namespace.
`spec.a2aServerRef`	object (`{name, namespace}`)	yes	The A2AServer the controller polls for task status. `name` is required; `namespace` defaults to the A2ATask’s namespace.
`spec.agentRef`	object (`{name, namespace}`)	yes	The Agent assigned to execute the task. `name` and `namespace` are both optional within the ref, but the `agentRef` object itself is required.
`spec.taskId`	string	yes	A2A protocol task identifier. `minLength: 1`.
`spec.contextId`	string	no	A2A conversation context id, linking related tasks into a stateful interaction. Mirrors the Query’s `status.response.a2a.contextId`.
`spec.input`	string	no	The user input that initiated the task.
`spec.parameters`	map[string]string	no	Additional key/value parameters passed to the remote agent.
`spec.priority`	int32	no	Execution order hint — higher values execute first. Default `0`.
`spec.timeout`	duration	no	How long the controller polls for a terminal state before marking the task `failed`. Default `12h`.
`spec.ttl`	duration	no	How long the A2ATask resource lingers after completion before it may be garbage-collected. Default `720h`.
`spec.pollInterval`	duration	no	How frequently the controller polls the A2A server for status updates. Default `5s`.

Dual lifecycle: phase vs protocol state

An A2ATask exposes the remote agent’s progress through two status fields. status.phase is Ark’s Kubernetes-native view and drives the Completed condition and print columns. status.protocolState is the verbatim A2A protocol state as reported by the server. The controller maps one to the other, but the value sets differ — for example, the protocol’s canceled (one l) maps to Ark’s cancelled (two ls), and protocol working maps to phase running.

A2A `protocolState`	Ark `status.phase`
`submitted`	`assigned`
`working`	`running`
`input-required`	`input-required`
`auth-required`	`auth-required`
`completed`	`completed`
`failed`	`failed`
`rejected`	`failed`
`canceled`	`cancelled`
`unknown`	`unknown`

Parts

Both artifacts and history messages carry content as typed parts (A2ATaskPart):

Field	Type	Required	Description
`kind`	enum (`text`, `file`, `data`)	yes	Content type of the part.
`text`	string	no	Text content, used when `kind: text`.
`data`	string	no	Base64-encoded binary content, used when `kind: data`.
`mimeType`	string	no	Content type, e.g. `text/plain`, `application/json`.
`uri`	string	no	External resource reference, used when `kind: file`.
`metadata`	map[string]string	no	Additional key/value pairs for the part.


parts:
  - kind: text
    text: "Temperature: 72°F, Conditions: Sunny"
  - kind: file
    uri: "https://weather.example.com/report.json"
    mimeType: "application/json"
  - kind: data
    data: "eyJkYXRhIjoiYmFzZTY0In0="          # base64-encoded bytes
    mimeType: "application/octet-stream"

Artifacts

Artifacts (status.artifacts[]) are structured outputs the remote agent produced during execution — reports, files, datasets, or media.

Field	Type	Required	Description
`artifactId`	string	yes	Unique identifier for the artifact within the task. `minLength: 1`.
`name`	string	no	Human-readable name.
`description`	string	no	Additional context about the artifact.
`parts[]`	list of `A2ATaskPart`	yes	The artifact content (see Parts).
`metadata`	map[string]string	no	Additional key/value pairs for the artifact.

History

History (status.history[]) is the complete conversation captured from the A2A protocol (A2ATaskMessage).

Field	Type	Required	Description
`messageId`	string	no	Protocol message id, used for deduplication.
`role`	enum (`user`, `agent`, `system`)	yes	Message sender.
`parts[]`	list of `A2ATaskPart`	yes	Message content (see Parts).
`metadata`	map[string]string	no	Additional key/value pairs for the message.

Status


status:
  phase: running                              # Ark lifecycle (see Phases)
  protocolState: working                      # A2A protocol state
  conditions:
    - type: Completed
      status: "False"                         # False while still in progress
      reason: TaskRunning
      message: Task is being executed
  startTime: "2025-01-15T10:30:00Z"
  completionTime: null
  contextId: "context-67890"
  artifacts:
    - artifactId: weather-data-001
      name: Weather Report
      description: Current weather conditions for New York City
      parts:
        - kind: text
          text: "Current temperature: 72°F, Humidity: 65%, Wind: 8 mph"
      metadata:
        source: WeatherAPI
  history:
    - messageId: msg-001
      role: user
      parts:
        - kind: text
          text: "What is the weather like in New York today?"
    - messageId: msg-002
      role: agent
      parts:
        - kind: text
          text: "The current weather in New York is 72°F with sunny conditions."
  protocolMetadata:
    session: sess-42
  lastStatusMessage:
    role: agent
    parts:
      - kind: text
        text: "Fetching current conditions…"
  lastStatusTimestamp: "2025-01-15T10:32:30Z"

Status fields

Field	Description
`status.phase`	Ark Kubernetes lifecycle stage (see Phases). Default `pending`.
`status.protocolState`	Raw A2A protocol state: `submitted`, `working`, `input-required`, `completed`, `canceled`, `failed`, `rejected`, `auth-required`, `unknown`.
`status.conditions[]`	Standard Kubernetes conditions. The `Completed` condition flips to `True` once the task is no longer running (regardless of outcome); `False` means still in progress.
`status.startTime`	When task execution began.
`status.completionTime`	When task execution finished (success or failure).
`status.error`	Error message if the task failed.
`status.contextId`	A2A conversation context this task belongs to.
`status.artifacts[]`	Outputs produced during execution — see Artifacts.
`status.history[]`	Full conversation from the A2A protocol — see History.
`status.protocolMetadata`	Additional key/value pairs from the A2A protocol.
`status.lastStatusMessage`	Most recent status message (`A2ATaskMessage`) from the protocol.
`status.lastStatusTimestamp`	When the protocol status was last updated (RFC3339 string).

Phases

status.phase values (enum):

Phase	Meaning
`pending`	Task created but not yet assigned. Default.
`assigned`	Task assigned to an agent (protocol `submitted`).
`running`	Remote agent is actively executing (protocol `working`).
`input-required`	Task is paused waiting for additional user input.
`auth-required`	Task is paused waiting for authentication.
`completed`	Execution finished successfully.
`failed`	Execution failed, was rejected, or the polling timeout elapsed. Details in `status.error`.
`cancelled`	Task was cancelled (protocol `canceled`).
`unknown`	State could not be determined.

Print columns

kubectl get a2atasks prints:

Column	Source
`NAME`	`.metadata.name`
`QUERY`	`.spec.queryRef.name`
`AGENT`	`.spec.agentRef.name`
`PHASE`	`.status.phase`
`AGE`	`.metadata.creationTimestamp`


kubectl get a2atasks
kubectl get a2atask task-weather-12345 -w      # watch progress
kubectl describe a2atask task-weather-12345    # full status, artifacts, history

A2AServer — discovers remote agents and is polled for task status via spec.a2aServerRef.
Query — originating request; its status.response.a2a.taskId references this A2ATask.
Agent — the target agent assigned via spec.agentRef, backed by the a2a execution engine.