capability.proto

Every Selu capability exposes a gRPC server that implements the CapabilityService defined below. The orchestrator calls Invoke when an agent uses the capability and HealthCheck to monitor liveness.

Service definition

capability.proto

syntax = "proto3";

package selu.capability.v1;

option go_package = "github.com/selu-platform/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;
}

Key design decisions

• JSON-encoded parameters — parameters_json and result_json use JSON strings rather than google.protobuf.Struct to give capability authors full control over serialization and to keep the proto dependency-free.
• Streaming support — InvokeStream lets capabilities push partial results (e.g. incremental search results or progress updates) back to the agent before the full result is ready.
• Conversation context — The orchestrator attaches recent conversation context so capabilities can make context-aware decisions without requiring the agent to pass everything explicitly.

Caution

The parameters_json field must be valid JSON that conforms to the spec.inputs declared in your manifest.yaml. The orchestrator validates the payload before forwarding it to your capability. Malformed JSON will result in an INVALID_ARGUMENT gRPC status.

Generating client/server code

Use buf or protoc to generate stubs in your language of choice:

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

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

The official Selu SDKs for Go and Python include pre-generated stubs, so you typically do not need to run code generation yourself.

Health checks

The orchestrator calls HealthCheck every 10 seconds. If a capability returns NOT_SERVING or fails to respond within 5 seconds, the orchestrator marks it as unhealthy and stops routing invocations to it until it recovers.