Agent Resources

An AgentResource is a Kubernetes CRD that represents an external resource agents can work with. It provides a declarative catalog entry for things like GitHub repositories, GitLab projects, S3 buckets, and documentation — along with the credentials needed to access them.

Resources are separate from agents by design. You declare a resource once, then bind it to any number of agents.

Why a separate CRD?

Without AgentResource, every agent that needs access to a repository would duplicate the owner, repo name, branch, and credential reference in its own spec. AgentResource centralizes that:

• One resource, many agents. A single agentops-core-repo AgentResource can be bound to a platform engineer, a code reviewer, and a security scanner.
• Credential isolation. The resource holds the secret reference. Agents only see a binding name — they never declare credentials directly.
• Console integration. The AgentOps Console uses AgentResource metadata to power the resource browser (files, commits, branches, MRs, issues) and resource context chips in the composer.
• Git workspace provisioning. AgentRuns reference an AgentResource to clone a repo, check out a branch, and give the task agent a ready-to-use /workspace.

Resource kinds

AgentResource supports seven kinds of external resources:

Each kind has its own configuration block. Exactly one must be set, matching the kind field.

Example: GitHub repository

apiVersion: agents.agentops.io/v1alpha1
kind: AgentResource
metadata:
  name: agentops-core-repo
  namespace: agents
spec:
  kind: github-repo
  displayName: AgentOps Core
  description: "AgentOps Kubernetes operator — CRDs, controllers, resource management"
  credentials:
    name: github-token
    key: GITHUB_TOKEN
  github:
    owner: samyn92
    repo: agentops-core
    defaultBranch: main

Example: GitLab project

apiVersion: agents.agentops.io/v1alpha1
kind: AgentResource
metadata:
  name: homecluster-repo
  namespace: agents
spec:
  kind: gitlab-project
  displayName: Homecluster
  description: "k3s homecluster GitOps repo — Flux, Helm, infrastructure"
  credentials:
    name: gitlab-token
    key: GITLAB_TOKEN
  gitlab:
    baseURL: https://gitlab.com
    project: samyn92/homecluster
    defaultBranch: main

Agent resource bindings

Agents bind to resources through spec.resourceBindings on the Agent CR. A binding is a lightweight reference — just a name and two optional flags:

apiVersion: agents.agentops.io/v1alpha1
kind: Agent
metadata:
  name: platform-engineer
  namespace: agents
spec:
  # ... model, tools, memory, etc.
  resourceBindings:
    - name: agentops-core-repo
    - name: homecluster-repo
      readOnly: true
    - name: platform-docs
      autoContext: true

Binding fields

The operator resolves all resource bindings during Agent reconciliation and sets the ResourcesReady condition on the Agent status. If any referenced AgentResource is missing or not in Ready phase, the agent will not reach Ready.

Git workspace for AgentRuns

AgentRuns can reference an AgentResource to get a fully provisioned git workspace. This is the primary mechanism for task agents that need to work on code:

apiVersion: agents.agentops.io/v1alpha1
kind: AgentRun
metadata:
  name: review-pr-42
  namespace: agents
spec:
  agentRef: code-reviewer
  prompt: "Review PR #42 on samyn92/agentops-core"
  source: channel
  sourceRef: github-prs
  git:
    resourceRef: agentops-core-repo   # AgentResource CR name
    branch: feature/new-crd
    baseBranch: main

When spec.git is set, the operator:

1. Resolves the AgentResource CR from resourceRef to get the clone URL and credentials.
2. Configures the Job pod to clone the repository and check out (or create) the feature branch.
3. Mounts the workspace at /workspace for the agent runtime.
4. After execution, the AgentRun status captures pullRequestURL, branch, and commits.

This works with github-repo, gitlab-project, and git-repo resource kinds.

Console integration

The AgentOps Console uses AgentResource metadata extensively:

• Resource browser — users can navigate repository files, commits, branches, merge requests, and issues directly from the console for github-repo and gitlab-project resources.
• Resource chips — in the composer, users attach resource chips to scope their prompt. The agent receives the selected resource context alongside the user’s message.
• Auto-context — resources with autoContext: true on their binding are injected into every prompt automatically, without the user selecting them.

How it flows through the system

Status and lifecycle

AgentResource has a simple lifecycle:

The controller validates that the kind-specific config block matches the kind field and sets a Ready condition. Additional validation (e.g. required fields within config blocks) is handled by the admission webhook.

$ kubectl get agentresources -n agents
NAME                       KIND              DISPLAY NAME       PHASE   AGE
agentops-core-repo         github-repo       AgentOps Core      Ready   5d
agentops-console-repo      github-repo       AgentOps Console   Ready   5d
agentops-runtime-repo      github-repo       AgentOps Runtime   Ready   5d
agentops-memory-repo       github-repo       AgentOps Memory    Ready   5d
agentops-platform-repo     github-repo       AgentOps Platform  Ready   5d
agent-tools-repo           github-repo       Agent Tools        Ready   5d
homecluster-repo           gitlab-project    Homecluster        Ready   5d

Kind-specific configuration reference

For the full field-by-field reference of each kind’s configuration block, see the CRD Reference.