capability.proto

Jede Selu-Capability stellt einen gRPC-Server bereit, der den unten definierten CapabilityService implementiert. Der Orchestrator ruft Invoke auf, wenn ein Agent die Capability nutzt, und HealthCheck, um die Erreichbarkeit zu überwachen.

Service-Definition

capability.proto

syntax = "proto3";

package selu.capability.v1;

option go_package = "github.com/selu-bot/selu/gen/capability/v1";

// CapabilityService is the interface every capability must implement.
service CapabilityService {
  // Invoke executes the capability with the given parameters and returns a result.
  rpc Invoke(InvokeRequest) returns (InvokeResponse);

  // InvokeStream executes the capability and streams partial results back.
  rpc InvokeStream(InvokeRequest) returns (stream InvokeResponse);

  // HealthCheck reports whether the capability is ready to accept requests.
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}

// InvokeRequest carries the parameters for a capability invocation.
message InvokeRequest {
  // Unique ID for this invocation, used for tracing and logging.
  string invocation_id = 1;

  // The agent that triggered this invocation.
  string agent_name = 2;

  // Input parameters as a JSON-encoded string matching the manifest's spec.inputs.
  string parameters_json = 3;

  // Optional context from the conversation (e.g. recent messages).
  ConversationContext context = 4;
}

message ConversationContext {
  string session_id = 1;
  string channel = 2;
  repeated Message recent_messages = 3;
}

message Message {
  string role = 1;   // "user", "assistant", or "system"
  string content = 2;
  int64 timestamp = 3; // Unix epoch milliseconds
}

// InvokeResponse carries the result of a capability invocation.
message InvokeResponse {
  // Output data as a JSON-encoded string matching the manifest's spec.outputs.
  string result_json = 1;

  // Indicates whether this is a partial (streaming) or final result.
  bool is_partial = 2;

  // Optional human-readable error message. If set, the invocation is treated as failed.
  string error = 3;
}

message HealthCheckRequest {}

message HealthCheckResponse {
  enum Status {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
  }
  Status status = 1;
}

Wichtige Designentscheidungen

• JSON-kodierte Parameter: parameters_json und result_json verwenden JSON-Strings statt google.protobuf.Struct. So behalten Capability-Autoren volle Kontrolle über die Serialisierung, und das Proto bleibt frei von zusätzlichen Abhängigkeiten.
• Streaming-Unterstützung: InvokeStream erlaubt es Capabilities, Teilergebnisse zurückzugeben, etwa inkrementelle Suchergebnisse oder Fortschrittsmeldungen, bevor das Gesamtergebnis fertig ist.
• Gesprächskontext: Der Orchestrator hängt aktuellen Gesprächskontext an, damit Capabilities kontextabhängige Entscheidungen treffen können, ohne dass der Agent alles explizit mitgeben muss.

Achtung

Das Feld parameters_json muss gültiges JSON sein und dem in manifest.yaml unter spec.inputs deklarierten Schema entsprechen. Der Orchestrator validiert das Payload vor dem Weiterleiten an die Capability. Ungültiges JSON führt zu einem gRPC-Status INVALID_ARGUMENT.

Client- und Server-Code generieren

Nutze buf oder protoc, um Stubs in deiner gewünschten Sprache zu erzeugen:

# Using buf (recommended)
buf generate proto/capability.proto

# Using protoc directly (Go example)
protoc --go_out=. --go-grpc_out=. proto/capability.proto

Die offiziellen Selu-SDKs für Go und Python enthalten bereits vorerzeugte Stubs. In der Praxis musst du die Code-Generierung daher oft gar nicht selbst ausführen.

Health-Checks

Der Orchestrator ruft HealthCheck alle 10 Sekunden auf. Wenn eine Capability NOT_SERVING zurückgibt oder nicht innerhalb von 5 Sekunden antwortet, markiert der Orchestrator sie als ungesund und leitet keine neuen Aufrufe mehr an sie weiter, bis sie sich erholt hat.