A2AServer

An A2AServer connects Ark to a remote Agent-to-Agent (A2A) protocol  server. Ark connects to the server, discovers the agents it hosts, and creates an Agent resource for each one — wired to the a2a execution engine so ordinary queries can target them. Each dispatched query then produces an A2ATask that Ark polls until the remote agent finishes.

API version: A2AServer is served under ark.mckinsey.com/v1prealpha1 — not the v1alpha1 group used by most Ark resources (Agent, Query, Model, …). Set apiVersion: ark.mckinsey.com/v1prealpha1 on every A2AServer manifest.

Spec

apiVersion: ark.mckinsey.com/v1prealpha1     # note: v1prealpha1, not v1alpha1
kind: A2AServer
metadata:
  name: aws-operator-agent
spec:
  # --- Required ----------------------------------------------------------
  # Endpoint of the A2A server. Inline 'value', or 'valueFrom' with
  # serviceRef / configMapKeyRef / secretKeyRef.
  address:
    value: http://ark-agentcore-bridge.default.svc.cluster.local:80/a2a/agent/aws_operator_agent
 
  # --- Optional ----------------------------------------------------------
  description: AWS operations agent with read-only access to AWS services
  # HTTP headers sent on every request, e.g. for authentication. Each value
  # is inline or sourced from a Secret/ConfigMap via valueFrom.
  headers:
    - name: Authorization
      value:
        valueFrom:
          secretKeyRef:
            name: a2a-credentials
            key: token
  pollInterval: 1m                            # how often to poll the server; default '1m'
  timeout: 5m                                 # A2A agent execution timeout; inherits Query.spec.timeout when unset
  # Which URL Ark calls for A2A requests: 'address' (default), 'cardPath', or
  # 'cardUrl'. See "Endpoint resolution" below.
  endpointResolution: cardPath
  # Hosts the agent card may redirect requests to, used only when
  # endpointResolution is 'cardUrl'. '*.' matches one level of subdomain,
  # an optional ':port' restricts the entry to that port.
  allowedEndpointHosts:
    - agents.example.com
    - agents-internal.example.com:8443
    - '*.a2a.example.com'

Fields

Discovery and created agents

When an A2AServer is created, the controller:

1. Discovers agents. It connects to spec.address and fetches the server’s agent card, trying /.well-known/agent-card.json (A2A v0.3+) first, then falling back to /.well-known/agent.json (A2A v0.2.x).
2. Creates an Agent per discovered agent. Each generated Agent has an owner reference to the A2AServer, executionEngine.name: a2a, and annotations recording the source server, resolved address, and discovered skills. A2A agents carry no modelRef — the remote server owns the model.
3. Monitors health. The controller re-polls on spec.pollInterval and keeps the Ready and Discovering conditions current.

Example Agent generated from the A2AServer above:

apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: aws-operator-agent
  annotations:
    ark.mckinsey.com/a2a-server-name: aws-operator-agent
    ark.mckinsey.com/a2a-server-address: http://ark-agentcore-bridge.default.svc.cluster.local:80/a2a/agent/aws_operator_agent
    ark.mckinsey.com/a2a-server-skills: '[{"name":"describe_ec2_instances","description":"List and describe EC2 instances in the account"}]'
spec:
  description: AWS operations agent with read-only access to AWS services
  prompt: You are aws_operator_agent. AWS operations agent with read-only access to AWS services
  executionEngine:
    name: a2a                                 # no modelRef — the remote A2A server owns the model

Endpoint resolution

The agent card the server returns carries its own url field, the endpoint the A2A spec says clients should send requests to. By default Ark ignores it and keeps calling spec.address, because a server’s card commonly advertises a URL that is not reachable from inside the cluster (http://localhost:8000, a public ingress hostname, or a placeholder). spec.endpointResolution opts a single A2AServer into trusting the card:

In both card modes the card URL must be an absolute http or https URL without userinfo. Anything else (a relative path, another scheme, user:password@host) is rejected with reason InvalidAgentCardURL.

cardUrl is the only mode that can move requests to a different host or port, and it is gated because spec.headers travel with the request: a card that repoints the endpoint would send your Secret-sourced credentials to whatever host it names. The card is refetched on every spec.pollInterval, so this is a standing delegation, not a one-time decision. spec.allowedEndpointHosts is therefore per-resource, so trusting one server does not trust the others.

Rejected overrides never break a working server. Ark falls back to spec.address, sets the EndpointOverride condition to False with the reason (CrossOriginNotAllowed, SchemeDowngrade, InvalidAgentCardURL, NoAgentCardURL, InvalidAddress, or UnsupportedTransport), records the rejected URL in status.rejectedEndpoint when there is one, and emits an EndpointOverrideRejected warning event whenever the reason or the rejected URL changes. When an override is applied, EndpointOverride is True with reason AgentCardEndpointApplied.

A rejected override looks like this in status:

status:
  conditions:
    - type: Ready
      status: "True"
      reason: AgentDiscovered
    - type: EndpointOverride
      status: "False"
      reason: CrossOriginNotAllowed
      message: Agent card URL points at weather.example.com:443, which is not the origin of spec.address and is not in spec.allowedEndpointHosts, using spec.address
  lastResolvedAddress: http://weather.default.svc.cluster.local:8000
  lastResolvedEndpoint: http://weather.default.svc.cluster.local:8000
  rejectedEndpoint: https://weather.example.com/a2a/v1

Transport

Ark speaks JSON-RPC only. In cardPath and cardUrl mode the endpoint it picks is the card’s JSON-RPC interface: url when preferredTransport is JSONRPC or unset, otherwise the first JSONRPC entry in additionalInterfaces. A card that declares no JSON-RPC interface is treated like any other rejected override: requests keep going to spec.address, EndpointOverride is False with reason UnsupportedTransport, and an UnsupportedTransport warning event names the transports the card does declare. Agents are still created and Ready is unaffected. In address mode the card transport is not inspected.

Conversation context

Ark does not hydrate conversation history into the message it sends a discovered agent: a query targeting one sends only that query’s current input, even when memory is active. Threading is opt-in — set the ark.mckinsey.com/a2a-context-id annotation on the query and Ark forwards that value as the A2A contextId, so a server that keys state on it links successive calls. Without the annotation Ark sends no contextId and each call stands alone. spec.conversationId threads the completions executor and named execution engines; it does not reach A2AServer agents. See A2A Queries → Stateful Messages for a worked example.

An agent running as a Team member is the exception: Ark renders the accumulated team transcript into the message, so the member sees earlier members’ turns without depending on server-side retention.

Status

status:
  conditions:
    - type: Ready                             # server reachable and operational
      status: "True"
      reason: AgentDiscovered
      message: Successfully discovered agent
    - type: Discovering                       # agent discovery in progress
      status: "False"
      reason: DiscoveryComplete
      message: Agent discovery completed
    - type: EndpointOverride                  # only present when endpointResolution != 'address'
      status: "True"
      reason: AgentCardEndpointApplied
      message: Using agent card endpoint http://ark-agentcore-bridge.default.svc.cluster.local:80/rpc
  lastResolvedAddress: http://ark-agentcore-bridge.default.svc.cluster.local:80/a2a/agent/aws_operator_agent
  lastResolvedEndpoint: http://ark-agentcore-bridge.default.svc.cluster.local:80/rpc

Status fields

Print columns

kubectl get a2aservers prints:

kubectl get a2aservers
kubectl describe a2aserver aws-operator-agent

Related

• Agent — Ark creates one per discovered agent, wired to the a2a execution engine.
• A2ATask — created per query and polled against this server via spec.a2aServerRef.
• Query — targets a discovered agent to run remote work.