agent-substrate / agent-substrate/substrate
[Feature Proposal] Support for Labeling and Filtering Substrate Entities
- 主要言語
- Go
- スター
- 1.8k
- フォーク
- 316
- 平均マージ
- 2日 43分
- マージ済み PR(30日)
- 287
説明
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 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.
```proto
message Actor {
...
// Labels associated with the actor.
map labels = 12;
}
message CreateActorRequest {
...
// Optional labels to apply to the actor upon creation.
map 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.
コントリビューションガイド
評価
この issue はまだ評価されていません。