Récif
Récifdocs

v0.1.0 · Apache 2.0

Search docs...

CRD Spec

Complete specification for the Agent Custom Resource Definition managed by the Recif operator.

6 min read

Overview

Recif uses a Kubernetes Custom Resource Definition (CRD) to declare agents. The Recif operator watches for Agent resources and reconciles them into running Deployments, Services, and ConfigMaps.

API Group: recif.dev API Version: v1 Kind: Agent

AgentSpec

The spec field defines the desired state of an agent.

FieldTypeDefaultRequiredDescription
namestring--YesHuman-readable name of the agent.
frameworkstring--YesAgent framework. Enum: adk, langchain, crewai, autogen, custom.
strategystringsimpleNoExecution strategy. Common values: simple, agent-react.
channelstringrestNoCommunication channel.
modelTypestringstubNoLLM provider key. Enum: stub, ollama, openai, anthropic, vertex-ai, bedrock, google-ai.
modelIdstringstub-echoNoModel identifier for the chosen provider.
systemPromptstring(empty)NoThe agent's instruction set.
storagestringmemoryNoConversation storage backend. Enum: memory, postgresql.
databaseUrlstring(empty)NoPostgreSQL connection string. Required when storage: postgresql.
tools[]string(empty)NoList of Tool CRD names assigned to this agent.
knowledgeBases[]string(empty)NoKnowledge base IDs for RAG strategy.
skills[]string(empty)NoSkill IDs assigned to this agent.
envSecrets[]string["agent-env"]NoSecret names whose data is injected as env vars. Defaults to ["agent-env"] when empty.
credentialSecretstringgcp-adcNoSecret containing a GCP/AWS credentials file to mount.
gcpServiceAccountstring(empty)NoGCP service account email. When set, the operator mounts {agent}-gcp-sa Secret and sets GOOGLE_APPLICATION_CREDENTIALS.
imagestringcorail:latestNoContainer image for the agent.
replicas*int321NoNumber of pod replicas. Min: 0, Max: 10.
suggestionsProviderstring(empty)NoSuggestion mode: llm (dynamic) or static (from config).
suggestionsstring(empty)NoJSON array of static suggestion strings.
evalSampleRateint320NoPercentage of production traces to auto-evaluate (0-100, 0 = disabled).
judgeModelstring(empty)NoModel ID for LLM-judge evaluation (e.g. openai:/gpt-4o-mini).
canary*CanarySpecnilNoCanary deployment configuration. See CanarySpec below.

CanarySpec

The canary field defines a challenger deployment to run alongside the stable version.

FieldTypeRequiredDescription
enabledboolYesWhether the canary deployment is active.
weightint32YesTraffic percentage routed to canary (1-100).
imagestringNoContainer image override for canary.
modelTypestringNoLLM provider override.
modelIdstringNoModel ID override.
systemPromptstringNoSystem prompt override.
skills[]stringNoSkills override for canary.
tools[]stringNoTools override for canary.
versionstringNoVersion label for the canary deployment.

AgentStatus

The status subresource is managed by the operator and reflects the observed state.

FieldTypeDescription
phaseAgentPhaseCurrent lifecycle phase. Enum: Pending, Running, Failed, Terminated.
replicasint32Observed number of ready replicas.
endpointstringIn-cluster service URL (e.g. http://support-agent.team-default.svc:8000).
conditions[]metav1.ConditionStandard Kubernetes conditions for detailed status.

AgentPhase Values

PhaseDescription
PendingAgent resource created, operator is provisioning.
RunningDeployment is healthy, pods are ready.
FailedDeployment has errors (crash loop, image pull failure).
TerminatedAgent has been stopped or deleted.

Print Columns

The CRD defines custom print columns for kubectl get agents:

ColumnTypeJSONPath
Phasestring.status.phase
Replicasinteger.status.replicas
Endpointstring.status.endpoint
Agedate.metadata.creationTimestamp

Minimal Example

The smallest valid Agent CRD with only required fields:

apiVersion: recif.dev/v1
kind: Agent
metadata:
  name: my-agent
  namespace: team-default
spec:
  name: "My Agent"
  framework: adk

This creates an agent with all defaults: stub model, simple strategy, rest channel, memory storage, 1 replica.

Full Example

A production-ready Agent CRD with all fields:

apiVersion: recif.dev/v1
kind: Agent
metadata:
  name: support-agent
  namespace: team-default
spec:
  # Identity
  name: "Support Agent"
  framework: adk
 
  # LLM
  modelType: openai
  modelId: gpt-4
  systemPrompt: |
    You are a customer support agent for Acme Corp.
    Be concise, helpful, and always provide sources.
 
  # Runtime
  strategy: agent-react
  channel: rest
  image: "ghcr.io/sciences44/corail:latest"
  replicas: 2
 
  # Storage
  storage: postgresql
  databaseUrl: "postgres://recif:recif_dev@recif-postgresql:5432/recif"
 
  # Capabilities
  tools:
    - web-search
    - ticket-lookup
  skills:
    - agui-render
    - code-review
  knowledgeBases:
    - kb_products
    - kb_faq
 
  # Secrets
  envSecrets:
    - agent-env
    - acme-api-keys
  credentialSecret: gcp-adc
  gcpServiceAccount: "support@acme-project.iam.gserviceaccount.com"
 
  # Suggestions
  suggestionsProvider: llm
  suggestions: '["How can I help?", "Check order status", "Return policy"]'
 
  # Evaluation
  evalSampleRate: 15
  judgeModel: "openai:/gpt-4o-mini"
 
  # Canary
  canary:
    enabled: false
    weight: 0

Applying Changes

# Create or update
kubectl apply -f support-agent.yaml
 
# Check status
kubectl get agents -n team-default
 
# Describe for events and conditions
kubectl describe agent support-agent -n team-default
 
# Delete
kubectl delete agent support-agent -n team-default

Note

The operator reconciles every 30 seconds. Changes to the CRD spec are picked up automatically and applied to the Deployment and ConfigMap.

Warning

Settingreplicas:0effectively stops the agent without deleting it. UsePOST/agents/{id}/stopvia the API for a controlled shutdown that also updates the database state.