[Feature Proposal] Support for Labeling and Filtering Substrate Entities

[MushuEE]

Currently, the Actor entity in Agent Substrate lacks support for arbitrary key-value metadata (labels/tags). As the platform grows, users and operators need a flexible way to categorize, group, and query active workloads without forcing database-specific indexing implementation requirements.

We propose adding a map<string, string> labels field to the Actor resource, enabling Kubernetes-style label selectors for filtering during ListActors requests.

Note

Performance Characteristic: ListActors is an operational control-plane query (used by command-line tools like kubectl-ate, admin UIs, and operator scripts) and is not on the latency-critical path for routing, scheduling, suspending, or resuming actors. Consequently, in-memory filtering at the service layer is acceptable and does not impact critical path latency.

---

User Stories & Use Cases

1. Ownership & Multi-Tenancy

• As a developer using a shared Substrate cluster, I want to filter actor listings to only see my own workloads (e.g. owner=alice).
• As a team lead, I want to list all actors billed to my team (e.g. team=checkout).

2. Environment & Resource Lifecycle Management

• As an operator, I want to run a cleanup script that lists all actors in staging (e.g. env=staging) and deletes/suspends them at the end of the day, without affecting production workloads.

3. Business & Workflow Context

• As a platform engineer, I want to look up an active agent instance by the customer id it is serving (e.g. customer_id=12345) to inspect its status or troubleshoot a support ticket.

4. Scheduler Placement constraints (Future proofing)

• As a scheduler developer, I want actors to carry constraints (e.g. gpu=required, region=us-central) so that the orchestrator can schedule them onto matching worker pods.

---

Proposed Design

1. Protobuf API Changes

We will update pkg/proto/ateapipb/ateapi.proto to include a labels map in the Actor message and the creation requests, along with a string-based label_selector for query filtering.

message Actor {
  ...
  // Labels associated with the actor.
  map<string, string> labels = 12;
}

message CreateActorRequest {
  ...
  // Optional labels to apply to the actor upon creation.
  map<string, string> labels = 4;
}

message ListActorsRequest {
  ...
  // An optional Kubernetes-style label selector query string (e.g. "env=production,app=billing").
  string label_selector = 3;
}

2. Database-Agnostic Filtering

To keep the persistence layer pluggable and simple:

• The Database Interface (store.Interface) will remain simple and only handle standard paginated key scanning. It will not know about the filter criteria.
• The Service Layer (controlapi.ListActors) will fetch the page of raw actors and apply the filter evaluation in memory using the Go k8s.io/apimachinery/pkg/labels package.
• Since our Redis storage driver uses protojson for marshaling/unmarshaling, the new labels field will automatically persist to Redis without requiring schema changes or updates to Redis Lua scripts.

---

Implementation Plan

1. Update pkg/proto/ateapipb/ateapi.proto and re-generate Go protobuf bindings.
2. Update the persistence layer interface and implementations to support setting and retrieving labels.
3. Integrate k8s.io/apimachinery/pkg/labels at the service layer in cmd/ateapi/internal/controlapi/list_actors.go to filter list results before returning them.
4. Add unit and integration tests covering label assignment, persistence, and selector querying.

[eliranw]

+1 from me, I’d use this. My case is plain metadata: tag actors with things like owner, app, or env and read it back on Get/List.

One thing I noticed though: the proposal only sets labels at creation, on CreateActorRequest. There’s no way to change them afterward. That’s fine for some of this, but we might also need re-labeling on an already existing actor, maybe for promotion of an actor between envs, or attaching metadata to an existing actor.

The Control service has no general update RPC today; actors only change through suspend, resume, and delete. So mutable labels would need a new RPC and a new write path, not just another field. Creation-only labels are basically free since protojson already persists them.

[dims]

Grant McCloskey (@MushuEE)

• How does filtering interact with pagination/page_size? (Are we filtering after a fixed-size raw page? so page_size may not be number of results?)
• user story 1: this is not a security boundary right? (alice can do owner=bob too)
• any bounds on the count/size of labels? (grpc limits? redis limits?)
• Guess we will want to update ActorTemplate controller to understand these as well?
• for labels, should we do inequality and set based grammar as well?

Also +1 to Mutability from eliranw above.

[thockin]

I think this is mostly fine, but I want to ask a few questions before we commit to the shape of it:

1. Can an ActorTemplate specify default labels? I guess that can be a distinct proposal, including which layer "wins" in case of conflict.

2. ListActors is something we need to think REALLLLY carefully about. If we have 100M actors and each on is a few hundred bytes, that is going to be tens of gigabytes of data. We HAVE to do some sort of pagination and we need to be careful that selectors are not too complex to evaluate.

3. We should spec the key and value format tightly. Probably just define it the same as k8s?

4. If a selector is a string we need to define a minimal grammar -- is it JUST an "and" expression or can we specify "or" and other boolean operators. What about other operators that emerged in k8s (in, notin, exists, ...)? It's OK if we don't solve these now, but we should not just pretend these problems don't exist. And I think defining a grammar is better than defining an AST in JSON. :)

5. We will need mutation of labels, almost certainly.

6. This is not a replacement for Design: Should Agent Substrate have its own concept of “namespaces”? #21 (namespaces)

[thockin]

FWIW I talked to Joe Betz (@jpbetz) about how he would retool k8s selectors if he could.

His suggestion was to stay a subset of CEL, even if we don't use the CEL evaluator. Something like:

==, !=, x in [a, b, c], !(x in [a, b, c]), ||, &&

label lookups would be something like labels["x"] == "value". By default CEL treats a failed map lookup as an error, but we could configure the map to think it has all keys, and just return and "undef" which is not equal to any value