gRPC API 参考

概述

Shannon 的内部架构使用 gRPC（HTTP/2 + Protocol Buffers）实现高性能服务间通信。本文档提供了所有 5 个服务和 39 个 RPC 方法的完整 Protocol Buffer 定义。

公共 vs 内部 API：gRPC 服务为内部接口，不通过公共 SDK 暴露。应用集成请使用网关 REST API（http://localhost:8080/api/v1/*）或 Python SDK（ShannonClient(base_url=...)）。

服务：

OrchestratorService（20 个 RPC）- 任务编排、工作流管理和调度
StreamingService（1 个 RPC）- 实时事件流
AgentService（6 个 RPC）- Agent 执行和工具管理
LLMService（5 个 RPC）- LLM 提供商网关
SessionService（7 个 RPC）- 多轮对话管理

总计：39 个 RPC 方法

通用类型

所有服务共享的类型。

ExecutionMode

enum ExecutionMode {
  EXECUTION_MODE_UNSPECIFIED = 0;
  EXECUTION_MODE_SIMPLE = 1;      // Direct tool/cache response
  EXECUTION_MODE_STANDARD = 2;    // Single agent with LLM
  EXECUTION_MODE_COMPLEX = 3;     // Multi-agent DAG execution
}

用途：确定任务执行策略

SIMPLE：直接工具调用或缓存查找（最快）
STANDARD：单 Agent LLM 驱动执行（平衡）
COMPLEX：多 Agent DAG 并行执行（功能最强）

ModelTier

enum ModelTier {
  MODEL_TIER_UNSPECIFIED = 0;
  MODEL_TIER_SMALL = 1;    // GPT-5-nano/mini, Haiku, 等等 (50% target)
  MODEL_TIER_MEDIUM = 2;   // GPT-5, Sonnet, 等等 (40% target)
  MODEL_TIER_LARGE = 3;    // GPT-5-turbo, Opus, 等等 (10% target)
}

成本优化：Shannon 在层级内自动选择模型以优化成本

Small：每 1K token $0.001-0.002
Medium：每 1K token $0.01-0.03
Large：每 1K token $0.03-0.075

StatusCode

enum StatusCode {
  STATUS_CODE_UNSPECIFIED = 0;
  STATUS_CODE_OK = 1;
  STATUS_CODE_ERROR = 2;
  STATUS_CODE_TIMEOUT = 3;
  STATUS_CODE_RATE_LIMITED = 4;
  STATUS_CODE_BUDGET_EXCEEDED = 5;
}

TaskMetadata

message TaskMetadata {
  string task_id = 1;
  string user_id = 2;
  string session_id = 3;
  string tenant_id = 4;
  google.protobuf.Timestamp created_at = 5;
  map<string, string> labels = 6;
  int32 max_agents = 7;       // Max concurrent agents (default: 5)
  double token_budget = 8;     // Token budget for this task
}

示例：

{
  "task_id": "task-123",
  "user_id": "user-456",
  "session_id": "sess-789",
  "tenant_id": "tenant-001",
  "labels": {
    "environment": "production",
    "priority": "high"
  },
  "max_agents": 10,
  "token_budget": 50000
}

TokenUsage

message TokenUsage {
  int32 prompt_tokens = 1;
  int32 completion_tokens = 2;
  int32 total_tokens = 3;
  double cost_usd = 4;
  string model = 5;
  ModelTier tier = 6;
}

ExecutionMetrics

message ExecutionMetrics {
  int64 latency_ms = 1;
  TokenUsage token_usage = 2;
  bool cache_hit = 3;
  double cache_score = 4;
  int32 agents_used = 5;
  ExecutionMode mode = 6;
}

OrchestratorService

任务编排和工作流管理服务。

服务定义

service OrchestratorService {
  rpc SubmitTask(SubmitTaskRequest) returns (SubmitTaskResponse);
  rpc GetTaskStatus(GetTaskStatusRequest) returns (GetTaskStatusResponse);
  rpc CancelTask(CancelTaskRequest) returns (CancelTaskResponse);
  rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
  rpc GetSessionContext(GetSessionContextRequest) returns (GetSessionContextResponse);
  rpc ListTemplates(ListTemplatesRequest) returns (ListTemplatesResponse);
  rpc ApproveTask(ApproveTaskRequest) returns (ApproveTaskResponse);
  rpc GetPendingApprovals(GetPendingApprovalsRequest) returns (GetPendingApprovalsResponse);
}

SubmitTask

提交新任务执行。请求：

message SubmitTaskRequest {
  TaskMetadata metadata = 1;
  string query = 2;
  google.protobuf.Struct context = 3;
  bool auto_decompose = 4;
  TaskDecomposition manual_decomposition = 5;
  SessionContext session_context = 6;
  bool require_approval = 10;
}

响应：

message SubmitTaskResponse {
  string workflow_id = 1;
  string task_id = 2;
  StatusCode status = 3;
  TaskDecomposition decomposition = 4;
  string message = 5;
}

示例（gRPC CLI）：

grpcurl -plaintext -d '{
  "metadata": {
    "user_id": "user-123",
    "session_id": "sess-456",
    "token_budget": 10000
  },
  "query": "Analyze Q4 sales data and create visualizations",
  "auto_decompose": true
}' localhost:50052 shannon.orchestrator.OrchestratorService/SubmitTask

响应：

{
  "workflow_id": "wf-550e8400-e29b-41d4-a716-446655440000",
  "task_id": "task-789",
  "status": "STATUS_CODE_OK",
  "decomposition": {
    "mode": "EXECUTION_MODE_COMPLEX",
    "complexity_score": 0.78,
    "agent_tasks": [
      {
        "agent_id": "data-loader",
        "description": "Load Q4 sales data",
        "required_tools": ["csv_loader"],
        "model_tier": "MODEL_TIER_SMALL"
      },
      {
        "agent_id": "analyst",
        "description": "Analyze sales trends",
        "dependencies": ["data-loader"],
        "model_tier": "MODEL_TIER_MEDIUM"
      },
      {
        "agent_id": "visualizer",
        "description": "Create charts",
        "dependencies": ["analyst"],
        "required_tools": ["matplotlib"],
        "model_tier": "MODEL_TIER_SMALL"
      }
    ]
  },
  "message": "Task submitted successfully"
}

GetTaskStatus

检索任务的当前状态和结果。请求：

message GetTaskStatusRequest {
  string task_id = 1;
  bool include_details = 2;
}

响应：

message GetTaskStatusResponse {
  string task_id = 1;
  TaskStatus status = 2;
  double progress = 3;              // 0.0 - 1.0
  string result = 4;
  ExecutionMetrics metrics = 5;
  repeated AgentTaskStatus agent_statuses = 6;
  string error_message = 7;
}

enum TaskStatus {
  TASK_STATUS_UNSPECIFIED = 0;
  TASK_STATUS_QUEUED = 1;
  TASK_STATUS_RUNNING = 2;
  TASK_STATUS_COMPLETED = 3;
  TASK_STATUS_FAILED = 4;
  TASK_STATUS_CANCELLED = 5;
  TASK_STATUS_TIMEOUT = 6;
}

示例：

grpcurl -plaintext -d '{
  "task_id": "task-789",
  "include_details": true
}' localhost:50052 shannon.orchestrator.OrchestratorService/GetTaskStatus

响应：

{
  "task_id": "task-789",
  "status": "TASK_STATUS_COMPLETED",
  "progress": 1.0,
  "result": "Analysis complete. Q4 revenue increased 15% YoY...",
  "metrics": {
    "latency_ms": 45000,
    "token_usage": {
      "total_tokens": 5420,
      "cost_usd": 0.0814,
      "model": "gpt-5"
    },
    "agents_used": 3,
    "mode": "EXECUTION_MODE_COMPLEX"
  },
  "agent_statuses": [
    {
      "agent_id": "data-loader",
      "status": "TASK_STATUS_COMPLETED",
      "result": "Loaded 15,000 records",
      "token_usage": {
        "total_tokens": 150,
        "cost_usd": 0.0003
      }
    }
  ]
}

CancelTask

取消正在运行的任务。请求：

message CancelTaskRequest {
  string task_id = 1;
  string reason = 2;
}

响应：

message CancelTaskResponse {
  bool success = 1;
  string message = 2;
}

ListTasks

列出任务，支持可选过滤。请求：

message ListTasksRequest {
  string user_id = 1;
  string session_id = 2;
  int32 limit = 3;
  int32 offset = 4;
  TaskStatus filter_status = 5;
}

响应：

message ListTasksResponse {
  repeated TaskSummary tasks = 1;
  int32 total_count = 2;
}

message TaskSummary {
  string task_id = 1;
  string query = 2;
  TaskStatus status = 3;
  ExecutionMode mode = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp completed_at = 6;
  TokenUsage total_token_usage = 7;
}

GetSessionContext

检索会话上下文和历史记录。请求：

message GetSessionContextRequest {
  string session_id = 1;
}

响应：

message GetSessionContextResponse {
  string session_id = 1;
  google.protobuf.Struct context = 2;
  repeated TaskSummary recent_tasks = 3;
  TokenUsage session_token_usage = 4;
}

ListTemplates

列出可用的任务模板。请求：

message ListTemplatesRequest {}

响应：

message ListTemplatesResponse {
  repeated TemplateSummary templates = 1;
}

message TemplateSummary {
  string name = 1;
  string version = 2;
  string key = 3;
  string content_hash = 4;
}

ApproveTask

批准或拒绝需要人工审批的任务。请求：

message ApproveTaskRequest {
  string approval_id = 1;
  string workflow_id = 2;
  string run_id = 3;
  bool approved = 4;
  string feedback = 5;
  string modified_action = 6;
  string approved_by = 7;
}

响应：

message ApproveTaskResponse {
  bool success = 1;
  string message = 2;
}

GetPendingApprovals

列出待审批请求。请求：

message GetPendingApprovalsRequest {
  string user_id = 1;
  string session_id = 2;
}

响应：

message GetPendingApprovalsResponse {
  repeated PendingApproval approvals = 1;
}

message PendingApproval {
  string approval_id = 1;
  string workflow_id = 2;
  string query = 3;
  string proposed_action = 4;
  string reason = 5;
  google.protobuf.Timestamp requested_at = 6;
  google.protobuf.Struct metadata = 7;
}

StreamingService

实时事件流服务。

服务定义

service StreamingService {
  rpc StreamTaskExecution(StreamRequest) returns (stream TaskUpdate);
}

StreamTaskExecution

流式传输任务的实时事件（服务器流式 RPC）。请求：

message StreamRequest {
  string workflow_id = 1;
  repeated string types = 2;      // Optional event type filter
  uint64 last_event_id = 3;       // Resume from this event (backward compat)
  string last_stream_id = 4;      // Resume from Redis stream ID (preferred)
}

响应（流）：

message TaskUpdate {
  string workflow_id = 1;
  string type = 2;                // Event type (see Event Types Catalog)
  string agent_id = 3;
  string message = 4;
  google.protobuf.Timestamp timestamp = 5;
  uint64 seq = 6;                 // Sequence number
  string stream_id = 7;           // Redis stream ID for resumption
}

示例（gRPC CLI）：

grpcurl -plaintext -d '{
  "workflow_id": "wf-550e8400-e29b-41d4-a716-446655440000"
}' localhost:50052 shannon.orchestrator.StreamingService/StreamTaskExecution

响应流：

{"workflow_id": "wf-...", "type": "WORKFLOW_STARTED", "message": "Task started", "seq": 1}
{"workflow_id": "wf-...", "type": "AGENT_STARTED", "agent_id": "data-loader", "seq": 2}
{"workflow_id": "wf-...", "type": "STATUS_UPDATE", "message": "Loading data...", "seq": 3}
{"workflow_id": "wf-...", "type": "TOOL_INVOKED", "message": "Invoking csv_loader", "seq": 4}
{"workflow_id": "wf-...", "type": "TOOL_OBSERVATION", "message": "Loaded 15,000 rows", "seq": 5}
...
{"workflow_id": "wf-...", "type": "WORKFLOW_COMPLETED", "message": "Task complete", "seq": 42}

事件类型过滤：

# 仅工作流生命周期事件
grpcurl -plaintext -d '{
  "workflow_id": "wf-...",
  "types": ["WORKFLOW_STARTED", "WORKFLOW_COMPLETED", "ERROR_OCCURRED"]
}' localhost:50052 shannon.orchestrator.StreamingService/StreamTaskExecution

流恢复：

# 从上次看到的事件恢复
grpcurl -plaintext -d '{
  "workflow_id": "wf-...",
  "last_stream_id": "1698765432000-0"
}' localhost:50052 shannon.orchestrator.StreamingService/StreamTaskExecution

参见事件类型目录了解所有事件类型。

AgentService

Agent 执行和工具管理服务。

服务定义

service AgentService {
  rpc ExecuteTask(ExecuteTaskRequest) returns (ExecuteTaskResponse);
  rpc StreamExecuteTask(ExecuteTaskRequest) returns (stream TaskUpdate);
  rpc GetCapabilities(GetCapabilitiesRequest) returns (GetCapabilitiesResponse);
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
  rpc DiscoverTools(DiscoverToolsRequest) returns (DiscoverToolsResponse);
  rpc GetToolCapability(GetToolCapabilityRequest) returns (GetToolCapabilityResponse);
}

ExecuteTask

使用单个 Agent 执行任务（一元 RPC）。请求：

message ExecuteTaskRequest {
  TaskMetadata metadata = 1;
  string query = 2;
  google.protobuf.Struct context = 3;
  ExecutionMode mode = 4;
  repeated string available_tools = 5;
  AgentConfig config = 6;
  SessionContext session_context = 7;
}

message AgentConfig {
  int32 max_iterations = 1;
  int32 timeout_seconds = 2;
  bool enable_sandbox = 3;
  int64 memory_limit_mb = 4;
  bool enable_learning = 5;
}

响应：

message ExecuteTaskResponse {
  string task_id = 1;
  StatusCode status = 2;
  string result = 3;
  repeated ToolCall tool_calls = 4;
  repeated ToolResult tool_results = 5;
  ExecutionMetrics metrics = 6;
  string error_message = 7;
  AgentState final_state = 8;
}

enum AgentState {
  AGENT_STATE_UNSPECIFIED = 0;
  AGENT_STATE_IDLE = 1;
  AGENT_STATE_PLANNING = 2;
  AGENT_STATE_EXECUTING = 3;
  AGENT_STATE_WAITING = 4;
  AGENT_STATE_COMPLETED = 5;
  AGENT_STATE_FAILED = 6;
}

StreamExecuteTask

执行任务并流式返回更新（服务器流式 RPC）。请求：与 ExecuteTask 相同响应（流）：

message TaskUpdate {
  string task_id = 1;
  AgentState state = 2;
  string message = 3;
  ToolCall tool_call = 4;
  ToolResult tool_result = 5;
  double progress = 6;
}

GetCapabilities

获取 Agent 能力。请求：

message GetCapabilitiesRequest {}

响应：

message GetCapabilitiesResponse {
  repeated string supported_tools = 1;
  repeated ExecutionMode supported_modes = 2;
  int64 max_memory_mb = 3;
  int32 max_concurrent_tasks = 4;
  string version = 5;
}

HealthCheck

检查 Agent 服务健康状态。请求：

message HealthCheckRequest {}

响应：

message HealthCheckResponse {
  bool healthy = 1;
  string message = 2;
  int64 uptime_seconds = 3;
  int32 active_tasks = 4;
  double memory_usage_percent = 5;
}

DiscoverTools

通过查询或类别发现可用工具。请求：

message DiscoverToolsRequest {
  string query = 1;
  repeated string categories = 2;
  repeated string tags = 3;
  bool exclude_dangerous = 4;
  int32 max_results = 5;
}

响应：

message DiscoverToolsResponse {
  repeated ToolCapability tools = 1;
}

message ToolCapability {
  string id = 1;
  string name = 2;
  string description = 3;
  string category = 4;
  google.protobuf.Struct input_schema = 5;
  google.protobuf.Struct output_schema = 6;
  repeated string required_permissions = 7;
  int64 estimated_duration_ms = 8;
  bool is_dangerous = 9;
  string version = 10;
  string author = 11;
  repeated string tags = 12;
  repeated ToolExample examples = 13;
  RateLimit rate_limit = 14;
  int64 cache_ttl_ms = 15;
}

示例：

grpcurl -plaintext -d '{
  "query": "data analysis",
  "categories": ["data"],
  "exclude_dangerous": true,
  "max_results": 10
}' localhost:50051 shannon.agent.AgentService/DiscoverTools

GetToolCapability

获取特定工具的详细能力。请求：

message GetToolCapabilityRequest {
  string tool_id = 1;
}

响应：

message GetToolCapabilityResponse {
  ToolCapability tool = 1;
}

LLMService

LLM 提供商网关服务。

服务定义

service LLMService {
  rpc GenerateCompletion(GenerateCompletionRequest) returns (GenerateCompletionResponse);
  rpc StreamCompletion(GenerateCompletionRequest) returns (stream CompletionChunk);
  rpc EmbedText(EmbedTextRequest) returns (EmbedTextResponse);
  rpc AnalyzeComplexity(AnalyzeComplexityRequest) returns (AnalyzeComplexityResponse);
  rpc ListModels(ListModelsRequest) returns (ListModelsResponse);
}

GenerateCompletion

生成 LLM 补全（一元 RPC）。请求：

message GenerateCompletionRequest {
  repeated Message messages = 1;
  ModelTier tier = 2;
  string specific_model = 3;
  GenerationConfig config = 4;
  TaskMetadata metadata = 5;
  repeated ToolDefinition available_tools = 6;
}

message Message {
  string role = 1;
  string content = 2;
  repeated ToolCall tool_calls = 3;
  string name = 4;
}

message GenerationConfig {
  double temperature = 1;
  double top_p = 2;
  int32 max_tokens = 3;
  repeated string stop_sequences = 4;
  double presence_penalty = 5;
  double frequency_penalty = 6;
  bool enable_caching = 7;
  string cache_key = 8;
}

响应：

message GenerateCompletionResponse {
  string completion = 1;
  repeated ToolCall tool_calls = 2;
  TokenUsage usage = 3;
  string model_used = 4;
  Provider provider = 5;
  bool cache_hit = 6;
  string finish_reason = 7;
}

enum Provider {
  PROVIDER_UNSPECIFIED = 0;
  PROVIDER_OPENAI = 1;
  PROVIDER_ANTHROPIC = 2;
  PROVIDER_GOOGLE = 3;
  PROVIDER_DEEPSEEK = 4;
  PROVIDER_QWEN = 5;
  PROVIDER_BEDROCK = 6;
  PROVIDER_OLLAMA = 7;
  PROVIDER_VLLM = 8;
}

StreamCompletion

生成流式 LLM 补全（服务器流式 RPC）。请求：与 GenerateCompletion 相同响应（流）：

message CompletionChunk {
  string delta = 1;
  ToolCall tool_call_delta = 2;
  string finish_reason = 3;
  TokenUsage usage = 4;
}

EmbedText

生成文本嵌入向量。请求：

message EmbedTextRequest {
  repeated string texts = 1;
  string model = 2;
}

响应：

message EmbedTextResponse {
  repeated Embedding embeddings = 1;
  int32 dimensions = 2;
  string model_used = 3;
}

message Embedding {
  repeated float vector = 1;
  string text = 2;
}

AnalyzeComplexity

分析查询复杂度并推荐执行模式。请求：

message AnalyzeComplexityRequest {
  string query = 1;
  google.protobuf.Struct context = 2;
  repeated string available_tools = 3;
}

响应：

message AnalyzeComplexityResponse {
  ExecutionMode recommended_mode = 1;
  double complexity_score = 2;
  repeated string required_capabilities = 3;
  int32 estimated_agents = 4;
  int32 estimated_tokens = 5;
  double estimated_cost_usd = 6;
  string reasoning = 7;
}

示例：

grpcurl -plaintext -d '{
  "query": "Analyze Q4 sales data and create visualizations",
  "available_tools": ["csv_loader", "pandas", "matplotlib"]
}' localhost:8000 shannon.llm.LLMService/AnalyzeComplexity

响应：

{
  "recommended_mode": "EXECUTION_MODE_COMPLEX",
  "complexity_score": 0.78,
  "required_capabilities": ["data_loading", "analysis", "visualization"],
  "estimated_agents": 3,
  "estimated_tokens": 5000,
  "estimated_cost_usd": 0.08,
  "reasoning": "Task requires data loading, statistical analysis, and visualization generation"
}

ListModels

列出可用的 LLM 模型。请求：

message ListModelsRequest {
  ModelTier tier = 1;
  Provider provider = 2;
}

响应：

message ListModelsResponse {
  repeated ModelInfo models = 1;
}

message ModelInfo {
  string id = 1;
  string name = 2;
  Provider provider = 3;
  ModelTier tier = 4;
  int32 context_window = 5;
  double cost_per_1k_prompt_tokens = 6;
  double cost_per_1k_completion_tokens = 7;
  bool supports_tools = 8;
  bool supports_streaming = 9;
  bool available = 10;
}

SessionService

多轮对话管理服务。

服务定义

service SessionService {
  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
  rpc GetSession(GetSessionRequest) returns (GetSessionResponse);
  rpc UpdateSession(UpdateSessionRequest) returns (UpdateSessionResponse);
  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse);
  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
  rpc AddMessage(AddMessageRequest) returns (AddMessageResponse);
  rpc ClearHistory(ClearHistoryRequest) returns (ClearHistoryResponse);
}

CreateSession

创建新的对话会话。请求：

message CreateSessionRequest {
  string user_id = 1;
  google.protobuf.Struct initial_context = 2;
  int32 max_history = 3;       // Max messages to keep
  int32 ttl_seconds = 4;        // Session TTL
}

响应：

message CreateSessionResponse {
  string session_id = 1;
  google.protobuf.Timestamp created_at = 2;
  google.protobuf.Timestamp expires_at = 3;
  StatusCode status = 4;
  string message = 5;
}

GetSession

检索会话详细信息。请求：

message GetSessionRequest {
  string session_id = 1;
  bool include_history = 2;
}

响应：

message GetSessionResponse {
  Session session = 1;
  StatusCode status = 2;
  string message = 3;
}

message Session {
  string id = 1;
  string user_id = 2;
  google.protobuf.Struct context = 3;
  repeated Message history = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp last_active = 6;
  google.protobuf.Timestamp expires_at = 7;
  SessionMetrics metrics = 8;
}

UpdateSession

更新会话上下文或延长 TTL。请求：

message UpdateSessionRequest {
  string session_id = 1;
  google.protobuf.Struct context_updates = 2;
  int32 extend_ttl_seconds = 3;
}

响应：

message UpdateSessionResponse {
  bool success = 1;
  google.protobuf.Timestamp new_expires_at = 2;
  StatusCode status = 3;
  string message = 4;
}

DeleteSession

删除会话。请求：

message DeleteSessionRequest {
  string session_id = 1;
}

响应：

message DeleteSessionResponse {
  bool success = 1;
  StatusCode status = 2;
  string message = 3;
}

ListSessions

列出用户会话。请求：

message ListSessionsRequest {
  string user_id = 1;
  bool active_only = 2;
  int32 limit = 3;
  int32 offset = 4;
}

响应：

message ListSessionsResponse {
  repeated SessionSummary sessions = 1;
  int32 total_count = 2;
  StatusCode status = 3;
  string message = 4;
}

message SessionSummary {
  string id = 1;
  string user_id = 2;
  google.protobuf.Timestamp created_at = 3;
  google.protobuf.Timestamp last_active = 4;
  int32 message_count = 5;
  int32 total_tokens = 6;
  bool is_active = 7;
}

AddMessage

向会话历史记录添加消息。请求：

message AddMessageRequest {
  string session_id = 1;
  Message message = 2;
}

message Message {
  string id = 1;
  string role = 2;              // "user", "assistant", "system"
  string content = 3;
  google.protobuf.Timestamp timestamp = 4;
  int32 tokens_used = 5;
  google.protobuf.Struct metadata = 6;
}

响应：

message AddMessageResponse {
  bool success = 1;
  int32 history_size = 2;
  StatusCode status = 3;
  string message = 4;
}

ClearHistory

清除会话消息历史记录。请求：

message ClearHistoryRequest {
  string session_id = 1;
  bool keep_context = 2;        // Keep persistent context
}

响应：

message ClearHistoryResponse {
  bool success = 1;
  StatusCode status = 2;
  string message = 3;
}

错误处理

状态码

所有响应都包含 StatusCode：

STATUS_CODE_OK (1) - 成功
STATUS_CODE_ERROR (2) - 通用错误
STATUS_CODE_TIMEOUT (3) - 操作超时
STATUS_CODE_RATE_LIMITED (4) - 超出速率限制
STATUS_CODE_BUDGET_EXCEEDED (5) - 超出 token/成本预算

gRPC 状态码

使用的标准 gRPC 状态码：

OK (0) - 成功
CANCELLED (1) - 请求已取消
INVALID_ARGUMENT (3) - 无效的请求参数
DEADLINE_EXCEEDED (4) - 超时
NOT_FOUND (5) - 资源未找到
ALREADY_EXISTS (6) - 资源已存在
PERMISSION_DENIED (7) - 权限不足
RESOURCE_EXHAUSTED (8) - 超出速率限制/配额
UNAUTHENTICATED (16) - 缺少/无效凭据
UNAVAILABLE (14) - 服务不可用
INTERNAL (13) - 内部服务器错误

错误处理示例（Python）

import grpc
from shannon.orchestrator import orchestrator_pb2, orchestrator_pb2_grpc

channel = grpc.insecure_channel('localhost:50052')
stub = orchestrator_pb2_grpc.OrchestratorServiceStub(channel)

try:
    response = stub.SubmitTask(
        orchestrator_pb2.SubmitTaskRequest(
            query="Analyze data",
            metadata=orchestrator_pb2.TaskMetadata(user_id="user-123")
        )
    )

    if response.status == orchestrator_pb2.STATUS_CODE_OK:
        print(f"Task submitted: {response.workflow_id}")
    else:
        print(f"Error: {response.message}")

except grpc.RpcError as e:
    if e.code() == grpc.StatusCode.UNAUTHENTICATED:
        print("Authentication required")
    elif e.code() == grpc.StatusCode.RESOURCE_EXHAUSTED:
        print("Rate limit exceeded")
    elif e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
        print("Request timeout")
    else:
        print(f"gRPC error: {e.code()} - {e.details()}")

服务端点

服务	默认端口	协议	TLS
OrchestratorService	50052	gRPC (HTTP/2)	可选
StreamingService	50052	gRPC (HTTP/2)	可选
AgentService	50051	gRPC (HTTP/2)	可选
LLMService	8000	gRPC (HTTP/2)	可选
SessionService	50052	gRPC (HTTP/2)	可选

Gateway REST API 也可在端口 8080 上使用（gRPC 的 HTTP/REST 包装器）。参见 REST API 参考了解 HTTP 端点。

代码生成

从 .proto 文件生成客户端代码：

Python

python -m grpc_tools.protoc \
  -I protos \
  --python_out=. \
  --grpc_python_out=. \
  protos/**/*.proto

Go

protoc -I protos \
  --go_out=. \
  --go-grpc_out=. \
  protos/**/*.proto

TypeScript

protoc -I protos \
  --ts_out=. \
  --grpc_out=. \
  protos/**/*.proto

REST API

HTTP REST 端点

事件类型

流事件目录

Python SDK

Python 客户端库

数据库架构

数据持久化

​概述

​通用类型

​ExecutionMode

​ModelTier

​StatusCode

​TaskMetadata

​TokenUsage

​ExecutionMetrics

​OrchestratorService

​服务定义

​SubmitTask

​GetTaskStatus

​CancelTask

​ListTasks

​GetSessionContext

​ListTemplates

​ApproveTask

​GetPendingApprovals

​StreamingService

​服务定义

​StreamTaskExecution

​AgentService

​服务定义

​ExecuteTask

​StreamExecuteTask

​GetCapabilities

​HealthCheck

​DiscoverTools

​GetToolCapability

​LLMService

​服务定义

​GenerateCompletion

​StreamCompletion

​EmbedText

​AnalyzeComplexity

​ListModels

​SessionService

​服务定义

​CreateSession

​GetSession

​UpdateSession

​DeleteSession

​ListSessions

​AddMessage

​ClearHistory

​错误处理

​状态码

​gRPC 状态码

​错误处理示例（Python）

​服务端点

​代码生成

​Python

​Go

​TypeScript

​相关主题

REST API

事件类型

Python SDK

数据库架构

概述

通用类型

ExecutionMode

ModelTier

StatusCode

TaskMetadata

TokenUsage

ExecutionMetrics

OrchestratorService

服务定义

SubmitTask

GetTaskStatus

CancelTask

ListTasks

GetSessionContext

ListTemplates

ApproveTask

GetPendingApprovals

StreamingService

服务定义

StreamTaskExecution

AgentService

服务定义

ExecuteTask

StreamExecuteTask

GetCapabilities

HealthCheck

DiscoverTools

GetToolCapability

LLMService

服务定义

GenerateCompletion

StreamCompletion

EmbedText

AnalyzeComplexity

ListModels

SessionService

服务定义

CreateSession

GetSession

UpdateSession

DeleteSession

ListSessions

AddMessage

ClearHistory

错误处理

状态码

gRPC 状态码

错误处理示例（Python）

服务端点

代码生成

Python

Go

TypeScript

相关主题