Agent

An Agent is an execution unit that runs a prompt against a model and can call tools. It resolves a Model (directly or via the default Model), runs on the built-in completions executor or a named ExecutionEngine, and can expose other tools — including HTTP tools, MCP servers, and even other agents or teams — to the model. For a task-oriented walkthrough see User Guide → Agents; this page is the field-by-field reference.

Spec


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: example-agent
spec:
  # --- Common optional fields --------------------------------------------
  prompt: |                                    # system prompt; supports {{.name}} templating
    You are a helpful assistant.
  description: General-purpose assistant agent  # human-readable description
 
  modelRef:                                     # Model to use; defaults to Model named 'default' if omitted
    name: gpt-4-model
    namespace: default                          # optional; defaults to the agent's namespace
 
  executionEngine:                              # optional; uses the built-in completions executor if unset
    name: langchain-engine
    namespace: default                          # optional; defaults to the agent's namespace
 
  tools:                                        # tools exposed to the model
    - type: http                                # built-in | custom | mcp | http | agent | team | builtin
      name: my-http-tool                        # required (minLength 1) unless type is built-in
    - type: mcp
      name: my-mcp-tool
 
  parameters:                                   # values for {{.name}} templating in prompt
    - name: api_endpoint
      valueFrom:
        configMapKeyRef:
          name: config
          key: endpoint
    - name: agent_name
      valueFrom:
        queryParameterRef:
          name: agent_name
 
  outputSchema:                                 # JSON schema for structured output
    type: object
    properties:
      summary:
        type: string
      confidence:
        type: number
 
  overrides:                                    # HTTP header overrides for downstream model / MCP calls
    - resourceType: model                       # model | mcpserver
      headers:
        - name: X-User-ID
          value:
            value: "user123"
      labelSelector:
        matchLabels:
          provider: openai

Fields

Field	Type	Required	Description
`spec.prompt`	string	no	System prompt defining the agent’s behavior. Supports Go template substitution via `{{.name}}` against `spec.parameters`.
`spec.description`	string	no	Human-readable description of the agent.
`spec.modelRef`	object	no	Model the agent uses. If omitted, defaults to a `Model` named `default` in the agent’s namespace.
`spec.modelRef.name`	string	yes (when `modelRef` set)	Name of the `Model` resource (minLength 1).
`spec.modelRef.namespace`	string	no	Namespace of the `Model`. Defaults to the agent’s namespace.
`spec.executionEngine`	object	no	Named `ExecutionEngine` to run this agent (e.g. LangChain, A2A). If unset, the built-in completions executor is used.
`spec.executionEngine.name`	string	yes (when `executionEngine` set)	Name of the `ExecutionEngine` resource (minLength 1).
`spec.executionEngine.namespace`	string	no	Namespace of the `ExecutionEngine`. Defaults to the agent’s namespace.
`spec.tools[]`	list	no	Tools exposed to the model. See Tool types.
`spec.tools[].type`	enum (`built-in`, `custom`, `mcp`, `http`, `agent`, `team`, `builtin`)	yes	Kind of tool. `built-in`/`builtin` are controller-provided (e.g. `terminate`, `noop`) and need no `Tool` CRD; `http`, `mcp`, and `custom` reference a `Tool` CRD; `agent` and `team` reference another `Agent` or `Team` in the same namespace.
`spec.tools[].name`	string	conditional	Name exposed to the model (minLength 1). Required for every type except `built-in`. For non-built-in types it must match a resource of that type in the namespace, unless overridden by `partial.name`.
`spec.tools[].description`	string	no	Description of the tool as exposed to the model.
`spec.tools[].functions[]`	list	no	Preconfigured function values (`name` + `value` or `valueFrom`) passed to the tool.
`spec.tools[].partial`	object	no	Overrides the tool’s exposed name and preconfigures/hides parameters from the model. See Partial tools.
`spec.parameters[]`	list	no	Template values substituted into `spec.prompt`. Each entry has a `name` (minLength 1) and either a `value` or `valueFrom` (`configMapKeyRef`, `secretKeyRef`, `serviceRef`, `queryParameterRef`). `value` and `valueFrom` are mutually exclusive.
`spec.outputSchema`	JSON schema	no	JSON schema for structured output. Preserves unknown fields — supply any valid JSON Schema object.
`spec.overrides[]`	list	no	HTTP header overrides applied when the agent calls its model or an MCP server. See Overrides.

Tool types

spec.tools[].type accepts:

Type	References	Notes
`built-in` / `builtin`	none	Controller-provided tools such as `terminate` and `noop`. No `Tool` CRD lookup; not validated.
`http`	a `Tool` CRD of type `http`	HTTP endpoint tool.
`mcp`	a `Tool` CRD of type `mcp`	Tool served by an MCP server.
`custom`	a `Tool` CRD	Deprecated generic type; the CRD type is not cross-checked.
`agent`	another `Agent`	Lets the agent call another agent as a tool.
`team`	a `Team`	Lets the agent call a team as a tool.

The controller validates that non-built-in tools exist in the agent’s namespace and that the declared type matches the referenced Tool CRD’s spec.type (except for custom).

Agent and team tools

An agent can expose another Agent or a Team to the model as a callable tool:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: coordinator
spec:
  prompt: |
    You coordinate specialists. Delegate sub-tasks to the tools available.
  tools:
    - type: agent
      name: research-agent            # another Agent in this namespace
    - type: team
      name: review-team               # a Team in this namespace

Overrides

Inject HTTP headers when the agent calls its model or an MCP server. resourceType is model or mcpserver; an optional labelSelector scopes the override to matching resources. Header values can be literal (value) or sourced (valueFrom).


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: custom-headers-agent
spec:
  prompt: You are a helpful assistant.
  overrides:
    - resourceType: model
      headers:
        - name: X-User-ID
          value:
            valueFrom:
              secretKeyRef:
                name: user-session
                key: user-id
        - name: X-Request-Context
          value:
            value: "production"
      labelSelector:
        matchLabels:
          provider: openai

See Overrides for details.

Partial tools

partial binds an agent tool to a real Tool CRD under a different exposed name and preconfigures (or hides) parameters. Parameters set in partial.parameters are injected at runtime and are not visible or editable by the model.


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: my-agent
spec:
  tools:
    - type: http
      name: weather-forecast              # name exposed to the model
      description: "Get latest weather forecast"
      partial:
        name: weather-api                 # actual Tool CRD name (type: http)
        parameters:
          - name: city
            value: "{{ .Query.city }}"    # from query parameters
          - name: units
            value: "metric"               # static value
          - name: language
            value: nil                    # exclude; leave for the model to supply

Examples

Simple agent


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: simple-agent
spec:
  prompt: You are a helpful assistant.

Agent with tools


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: weather-agent
spec:
  prompt: |
    You are a weather forecasting assistant.
    Use the available tools to get weather information.
  tools:
    - type: http
      name: get-coordinates
    - type: http
      name: get-forecast

Structured output


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: analyzer
spec:
  prompt: Analyze the input and provide structured feedback.
  outputSchema:
    type: object
    required: [sentiment, confidence]
    properties:
      sentiment:
        type: string
        enum: [positive, negative, neutral]
      confidence:
        type: number
        minimum: 0
        maximum: 1

Templated prompt from ConfigMap


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: policy-reviewer
spec:
  prompt: |
    You are a policy review assistant. Review documents according to these guidelines:
 
    Policy documents are located at: {{.policyDocumentsPath}}
 
    Use the following criteria for review:
    {{.reviewCriteria}}
  parameters:
    - name: policyDocumentsPath
      valueFrom:
        configMapKeyRef:
          name: policy-config
          key: documents-path
    - name: reviewCriteria
      valueFrom:
        configMapKeyRef:
          name: policy-config
          key: review-criteria

Query parameter reference


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: dynamic-agent
spec:
  prompt: |
    Your name is {{.agent_name}}.
    You operate in {{.mode}} mode.
    Your expertise level is {{.expertise_level}}.
  parameters:
    - name: agent_name
      valueFrom:
        queryParameterRef:                # resolved from the Query's parameters at runtime
          name: agent_name
    - name: mode
      valueFrom:
        queryParameterRef:
          name: operation_mode
    - name: expertise_level
      value: "expert"                     # static value

See Query → Pass parameter values at query time for the dashboard walkthrough.

A2A agent (created by an A2AServer)

Agents created by A2AServer resources run on the a2a execution engine and are owned by the A2AServer:


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-jg0yD9Hv2n
    ark.mckinsey.com/a2a-server-skills: '[{"name":"describe_ec2_instances","description":"List and describe EC2 instances"}]'
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
  # modelRef omitted — A2A agents do not require a model.
  # If set, the agent shows Available only when both the model and the A2AServer are available;
  # otherwise only A2AServer availability is checked.

Reconciliation behavior

The agent controller continuously reconciles agents to ensure their dependencies resolve, writing the result to the Available condition.

Model resolution

When spec.modelRef is set, the controller checks the referenced Model exists and has its ModelAvailable condition True. Missing → Available: False with reason ModelNotFound; present but not available → Available: False with a “not available” message.
A2A agents (those owned by an A2AServer) can omit modelRef — availability is governed by the owning A2AServer, not a model.

Tool resolution

Built-in tools (built-in/builtin) are always available and are not validated.
Other tools must exist in the agent’s namespace and their declared type must match the referenced Tool CRD’s spec.type (except custom). A missing tool sets Available: False with reason ToolNotFound.

Execution engine resolution

The built-in a2a engine needs no ExecutionEngine CR. Any other named engine must exist and be in phase ready; otherwise Available: False with reason ExecutionEngineNotFound or ExecutionEngineNotReady.

Dependency watching

The controller watches Model, Tool, ExecutionEngine, and A2AServer resources and re-reconciles dependent agents on change, so an agent automatically becomes Available once its missing dependencies resolve.

Status


status:
  conditions:
    - type: Available
      status: "True"
      reason: Available
      message: All dependencies are available

Status fields

Field	Description
`status.conditions[]`	Standard Kubernetes conditions. The `Available` condition reports readiness.
`Available` = `True`	All dependencies (model, tools, execution engine, A2AServer) resolve. Reason `Available`.
`Available` = `False`	A dependency is missing or not ready. Reasons include `ModelNotFound`, `ToolNotFound`, `ExecutionEngineNotFound`, `ExecutionEngineNotReady`, `A2AServerNotReady`.
`Available` = `Unknown`	Availability is still being determined (reason `Initializing`).

Print columns

kubectl get agents prints NAME, MODEL (.spec.modelRef.name), AVAILABLE (the Available condition status), and AGE.

User Guide → Agents — task-oriented walkthrough.
Models — the model an agent runs against (spec.modelRef).
Tools — tools referenced by spec.tools.
Query — dispatch work to an agent (target.type: agent).
A2AServer — creates A2A-backed agents.
Overrides — header overrides via spec.overrides.