Query

Queries represent execution requests sent to agents or teams. They support both simple string inputs and structured conversation messages with template parameter expansion.

Specification


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: example-query
spec:
  # Input type: "user" (default) or "messages"
  type: user
 
  # For type: user - simple string input
  input: "What is the weather in {{.location}}?"
 
  # OR for type: messages - structured conversation array
  # input:
  #   - role: user
  #     content: "Calculate 1+1"
  #   - role: assistant
  #     content: "2"
  #   - role: user
  #     content: "Calculate 2+2"
 
  # Template parameters for input expansion
  parameters:
    - name: location
      value: "New York"
    - name: api_key
      valueFrom:
        secretKeyRef:
          name: weather-api
          key: token
 
  # Execution targets
  targets:
    - type: agent
      name: weather-agent
    - type: team
      name: forecast-team
 
  # Optional: session identifier for conversation continuity
  sessionId: user-session-123
 
  # Optional: memory storage for conversation history
  memory:
    name: cluster-memory
 
  # Optional: timeout for query execution
  timeout: 5m
 
  # Optional: header overrides for models and MCP servers
  overrides:
    - headers:
        - name: X-Trace-ID
          value:
            value: "trace-xyz789"
      resourceType: model
 
status:
  # Execution state: pending, running, done, error
  phase: done
 
  # Responses from each target
  responses:
    - target:
        type: agent
        name: weather-agent
      content: "It's 72°F and sunny in New York"
 
  # A2A protocol metadata (when targeting A2A agents)
  a2a:
    contextId: "ctx-abc123"
    taskId: "task-xyz789"

Input Types

User Input (Default)

Simple string input, treated as a single user message. Supports template parameter expansion.


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: simple-query
spec:
  # Type is optional - defaults to "user"
  input: "What is the capital of {{.country}}?"
  parameters:
    - name: country
      value: "France"
  targets:
    - type: agent
      name: geography-agent

Messages Input

Structured conversation array for multi-turn conversations with role attribution.


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: conversation-query
spec:
  type: messages
  input:
    - role: user
      content: "Calculate 1+1"
    - role: assistant
      content: "2"
    - role: user
      content: "Now calculate 2+2"
  targets:
    - type: agent
      name: math-agent

Supported roles:

user - User messages
assistant - Agent/assistant responses
system - System instructions (provider-specific)

Multimodal Messages

The messages type uses the standard OpenAI message structure, supporting multimodal content including image_url for vision capabilities:


kubectl apply -f samples/queries/query-messages-image-url.yaml
# Example output: "The image shows a black hexagonal shape with a small break in the bottom right corner, resembling the QuantumBlack logo"

Targets

Targets specify which resources should process the query. Supported types: agent, team, model, tool.


spec:
  input: "What's your recommendation?"
  targets:
    - type: agent
      name: data-analyst
    - type: team
      name: review-team
    - type: model
      name: gpt-4

Each target receives the same input and produces an independent response in status.responses[].

Query Parameter Expansion

Overview

Query parameters enable dynamic input through Go template syntax. Parameters are resolved from values, ConfigMaps, or Secrets.

Important: Parameter expansion only applies to type: user queries. For type: messages queries, message content is used as-is without template processing.

Parameter Sources


spec:
  input: "API: {{.endpoint}}, Key: {{.key}}, Mode: {{.mode}}"
  parameters:
    # Direct value
    - name: mode
      value: "production"
 
    # From ConfigMap
    - name: endpoint
      valueFrom:
        configMapKeyRef:
          name: api-config
          key: url
 
    # From Secret
    - name: key
      valueFrom:
        secretKeyRef:
          name: api-credentials
          key: api-key

Template Syntax

Use {{.parameter_name}} in the input string to reference parameters:


input: |
  Environment: {{.environment}}
  Database: {{.db_host}}:{{.db_port}}
  User: {{.db_user}}

Parameters are resolved before the query is sent to the target agent or team.

Agent Parameters

Agent prompts can reference query parameters using queryParameterRef, allowing agents to access values from the query at runtime:


# Agent with query parameter reference
apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: dynamic-agent
spec:
  prompt: |
    You are operating in {{.mode}} mode.
    Target environment: {{.environment}}
  parameters:
    - name: mode
      valueFrom:
        queryParameterRef:
          name: operation_mode
    - name: environment
      valueFrom:
        queryParameterRef:
          name: target_env
---
# Query providing parameters for the agent
apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: parameterized-query
spec:
  input: "Process this request"
  parameters:
    - name: operation_mode
      value: "production"
    - name: target_env
      value: "us-west-2"
  targets:
    - type: agent
      name: dynamic-agent

Session Management

Group related queries using sessionId to maintain conversation context:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: query-1
spec:
  sessionId: user-session-123
  memory:
    name: cluster-memory
  input: "Hello, my name is Alice"
  targets:
    - type: agent
      name: assistant
---
apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: query-2
spec:
  sessionId: user-session-123  # Same session
  memory:
    name: cluster-memory
  input: "What's my name?"
  targets:
    - type: agent
      name: assistant

The agent will remember “Alice” from the first query when processing the second.

Timeout Configuration

Control how long ARK waits for query execution before timing out:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: long-running-query
spec:
  input: "Perform deep analysis"
  targets:
    - type: agent
      name: research-agent
  timeout: 30m  # Wait up to 30 minutes (default: 5m)

Timeout format: Duration string (e.g., 30s, 5m, 1h, 30m)
Default: 5 minutes if not specified

Timeout Behavior

If execution completes within timeout → Query phase: done
If execution exceeds timeout → Query phase: error with timeout error message
Applies to all targets in the query

For A2A Agents

A2A execution automatically respects the query timeout. The A2A execution uses Go’s context deadline, so remaining time is automatically tracked as the query progresses.

Individual A2A servers can also have their own timeout configured via A2AServer.spec.timeout to further limit specific server calls.

See the Building A2A Servers guide for detailed timeout configuration for A2A agents.

Examples

Simple Query


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: hello-query
spec:
  input: "Hello, how are you?"
  targets:
    - type: agent
      name: assistant

Query with Parameters


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: weather-query
spec:
  input: "What's the weather in {{.city}} on {{.date}}?"
  parameters:
    - name: city
      value: "Boston"
    - name: date
      valueFrom:
        configMapKeyRef:
          name: query-config
          key: target-date
  targets:
    - type: agent
      name: weather-agent

Conversation with Messages


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: math-conversation
spec:
  type: messages
  input:
    - role: user
      content: "Calculate the sum of 15 and 27"
    - role: assistant
      content: "15 + 27 = 42"
    - role: user
      content: "Now multiply that result by 3"
  targets:
    - type: agent
      name: calculator

Multi-Target Query


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: opinion-poll
spec:
  input: "Should we deploy this feature?"
  targets:
    - type: agent
      name: product-manager
    - type: agent
      name: tech-lead
    - type: team
      name: qa-team

Query with Overrides

Add custom headers for model or MCP server requests:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: tracked-query
spec:
  input: "Analyze this data"
  targets:
    - type: agent
      name: data-analyst
  overrides:
    - headers:
        - name: X-Request-ID
          value:
            value: "req-12345"
        - name: X-User-Context
          value:
            valueFrom:
              configMapKeyRef:
                name: user-config
                key: context
      resourceType: model
      labelSelector:
        matchLabels:
          tier: production

See Overrides for detailed documentation.

Status and Phases

Phases

Phase	Description
pending	Query created, waiting to execute
running	Query executing on targets
done	All targets completed successfully
error	Query execution failed

Status Fields


status:
  phase: done
 
  # Response from each target
  responses:
    - target:
        type: agent
        name: weather-agent
        namespace: default
      content: "Current temperature is 72°F"
 
  # Execution timing
  startTime: "2025-10-02T10:00:00Z"
  completionTime: "2025-10-02T10:00:05Z"
 
  # A2A protocol metadata (populated when targeting A2A agents)
  a2a:
    contextId: "ctx-abc123"
    taskId: "task-xyz789"

A2A Protocol Metadata

When queries target agents hosted on A2A servers, the status.a2a field contains A2A protocol-specific metadata:


status:
  a2a:
    # Context identifier for grouping related interactions
    contextId: "ctx-abc123"
 
    # Task identifier if an A2ATask was created
    taskId: "task-xyz789"

contextId: Groups related queries in a conversation thread. Set via ark.mckinsey.com/a2a-context-id annotation on query creation.
taskId: References the A2ATask resource created for this query. See A2ATask for details.