> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.
# gRPC API 参考
> Shannon 内部 gRPC 服务的完整 Protocol Buffer 定义
## 概述
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
```protobuf theme={null}
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
```protobuf theme={null}
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
```protobuf theme={null}
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
```protobuf theme={null}
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 labels = 6;
int32 max_agents = 7; // Max concurrent agents (default: 5)
double token_budget = 8; // Token budget for this task
}
```
**示例**：
```json theme={null}
{
"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
```protobuf theme={null}
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
```protobuf theme={null}
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
任务编排和工作流管理服务。
### 服务定义
```protobuf theme={null}
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
提交新任务执行。
**请求**：
```protobuf theme={null}
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;
}
```
**响应**：
```protobuf theme={null}
message SubmitTaskResponse {
string workflow_id = 1;
string task_id = 2;
StatusCode status = 3;
TaskDecomposition decomposition = 4;
string message = 5;
}
```
**示例**（gRPC CLI）：
```bash theme={null}
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
```
**响应**：
```json theme={null}
{
"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
检索任务的当前状态和结果。
**请求**：
```protobuf theme={null}
message GetTaskStatusRequest {
string task_id = 1;
bool include_details = 2;
}
```
**响应**：
```protobuf theme={null}
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;
}
```
**示例**：
```bash theme={null}
grpcurl -plaintext -d '{
"task_id": "task-789",
"include_details": true
}' localhost:50052 shannon.orchestrator.OrchestratorService/GetTaskStatus
```
**响应**：
```json theme={null}
{
"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
取消正在运行的任务。
**请求**：
```protobuf theme={null}
message CancelTaskRequest {
string task_id = 1;
string reason = 2;
}
```
**响应**：
```protobuf theme={null}
message CancelTaskResponse {
bool success = 1;
string message = 2;
}
```
***
### ListTasks
列出任务，支持可选过滤。
**请求**：
```protobuf theme={null}
message ListTasksRequest {
string user_id = 1;
string session_id = 2;
int32 limit = 3;
int32 offset = 4;
TaskStatus filter_status = 5;
}
```
**响应**：
```protobuf theme={null}
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
检索会话上下文和历史记录。
**请求**：
```protobuf theme={null}
message GetSessionContextRequest {
string session_id = 1;
}
```
**响应**：
```protobuf theme={null}
message GetSessionContextResponse {
string session_id = 1;
google.protobuf.Struct context = 2;
repeated TaskSummary recent_tasks = 3;
TokenUsage session_token_usage = 4;
}
```
***
### ListTemplates
列出可用的任务模板。
**请求**：
```protobuf theme={null}
message ListTemplatesRequest {}
```
**响应**：
```protobuf theme={null}
message ListTemplatesResponse {
repeated TemplateSummary templates = 1;
}
message TemplateSummary {
string name = 1;
string version = 2;
string key = 3;
string content_hash = 4;
}
```
***
### ApproveTask
批准或拒绝需要人工审批的任务。
**请求**：
```protobuf theme={null}
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;
}
```
**响应**：
```protobuf theme={null}
message ApproveTaskResponse {
bool success = 1;
string message = 2;
}
```
***
### GetPendingApprovals
列出待审批请求。
**请求**：
```protobuf theme={null}
message GetPendingApprovalsRequest {
string user_id = 1;
string session_id = 2;
}
```
**响应**：
```protobuf theme={null}
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
实时事件流服务。
### 服务定义
```protobuf theme={null}
service StreamingService {
rpc StreamTaskExecution(StreamRequest) returns (stream TaskUpdate);
}
```
***
### StreamTaskExecution
流式传输任务的实时事件（服务器流式 RPC）。
**请求**：
```protobuf theme={null}
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)
}
```
**响应**（流）：
```protobuf theme={null}
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）：
```bash theme={null}
grpcurl -plaintext -d '{
"workflow_id": "wf-550e8400-e29b-41d4-a716-446655440000"
}' localhost:50052 shannon.orchestrator.StreamingService/StreamTaskExecution
```
**响应流**：
```json theme={null}
{"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}
```
**事件类型过滤**：
```bash theme={null}
# 仅工作流生命周期事件
grpcurl -plaintext -d '{
"workflow_id": "wf-...",
"types": ["WORKFLOW_STARTED", "WORKFLOW_COMPLETED", "ERROR_OCCURRED"]
}' localhost:50052 shannon.orchestrator.StreamingService/StreamTaskExecution
```
**流恢复**：
```bash theme={null}
# 从上次看到的事件恢复
grpcurl -plaintext -d '{
"workflow_id": "wf-...",
"last_stream_id": "1698765432000-0"
}' localhost:50052 shannon.orchestrator.StreamingService/StreamTaskExecution
```
参见[事件类型目录](/cn/api/event-types)了解所有事件类型。
***
## AgentService
Agent 执行和工具管理服务。
### 服务定义
```protobuf theme={null}
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）。
**请求**：
```protobuf theme={null}
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;
}
```
**响应**：
```protobuf theme={null}
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` 相同
**响应**（流）：
```protobuf theme={null}
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 能力。
**请求**：
```protobuf theme={null}
message GetCapabilitiesRequest {}
```
**响应**：
```protobuf theme={null}
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 服务健康状态。
**请求**：
```protobuf theme={null}
message HealthCheckRequest {}
```
**响应**：
```protobuf theme={null}
message HealthCheckResponse {
bool healthy = 1;
string message = 2;
int64 uptime_seconds = 3;
int32 active_tasks = 4;
double memory_usage_percent = 5;
}
```
***
### DiscoverTools
通过查询或类别发现可用工具。
**请求**：
```protobuf theme={null}
message DiscoverToolsRequest {
string query = 1;
repeated string categories = 2;
repeated string tags = 3;
bool exclude_dangerous = 4;
int32 max_results = 5;
}
```
**响应**：
```protobuf theme={null}
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;
}
```
**示例**：
```bash theme={null}
grpcurl -plaintext -d '{
"query": "data analysis",
"categories": ["data"],
"exclude_dangerous": true,
"max_results": 10
}' localhost:50051 shannon.agent.AgentService/DiscoverTools
```
***
### GetToolCapability
获取特定工具的详细能力。
**请求**：
```protobuf theme={null}
message GetToolCapabilityRequest {
string tool_id = 1;
}
```
**响应**：
```protobuf theme={null}
message GetToolCapabilityResponse {
ToolCapability tool = 1;
}
```
***
## LLMService
LLM 提供商网关服务。
### 服务定义
```protobuf theme={null}
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）。
**请求**：
```protobuf theme={null}
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;
}
```
**响应**：
```protobuf theme={null}
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` 相同
**响应**（流）：
```protobuf theme={null}
message CompletionChunk {
string delta = 1;
ToolCall tool_call_delta = 2;
string finish_reason = 3;
TokenUsage usage = 4;
}
```
***
### EmbedText
生成文本嵌入向量。
**请求**：
```protobuf theme={null}
message EmbedTextRequest {
repeated string texts = 1;
string model = 2;
}
```
**响应**：
```protobuf theme={null}
message EmbedTextResponse {
repeated Embedding embeddings = 1;
int32 dimensions = 2;
string model_used = 3;
}
message Embedding {
repeated float vector = 1;
string text = 2;
}
```
***
### AnalyzeComplexity
分析查询复杂度并推荐执行模式。
**请求**：
```protobuf theme={null}
message AnalyzeComplexityRequest {
string query = 1;
google.protobuf.Struct context = 2;
repeated string available_tools = 3;
}
```
**响应**：
```protobuf theme={null}
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;
}
```
**示例**：
```bash theme={null}
grpcurl -plaintext -d '{
"query": "Analyze Q4 sales data and create visualizations",
"available_tools": ["csv_loader", "pandas", "matplotlib"]
}' localhost:8000 shannon.llm.LLMService/AnalyzeComplexity
```
**响应**：
```json theme={null}
{
"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 模型。
**请求**：
```protobuf theme={null}
message ListModelsRequest {
ModelTier tier = 1;
Provider provider = 2;
}
```
**响应**：
```protobuf theme={null}
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
多轮对话管理服务。
### 服务定义
```protobuf theme={null}
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
创建新的对话会话。
**请求**：
```protobuf theme={null}
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
}
```
**响应**：
```protobuf theme={null}
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
检索会话详细信息。
**请求**：
```protobuf theme={null}
message GetSessionRequest {
string session_id = 1;
bool include_history = 2;
}
```
**响应**：
```protobuf theme={null}
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。
**请求**：
```protobuf theme={null}
message UpdateSessionRequest {
string session_id = 1;
google.protobuf.Struct context_updates = 2;
int32 extend_ttl_seconds = 3;
}
```
**响应**：
```protobuf theme={null}
message UpdateSessionResponse {
bool success = 1;
google.protobuf.Timestamp new_expires_at = 2;
StatusCode status = 3;
string message = 4;
}
```
***
### DeleteSession
删除会话。
**请求**：
```protobuf theme={null}
message DeleteSessionRequest {
string session_id = 1;
}
```
**响应**：
```protobuf theme={null}
message DeleteSessionResponse {
bool success = 1;
StatusCode status = 2;
string message = 3;
}
```
***
### ListSessions
列出用户会话。
**请求**：
```protobuf theme={null}
message ListSessionsRequest {
string user_id = 1;
bool active_only = 2;
int32 limit = 3;
int32 offset = 4;
}
```
**响应**：
```protobuf theme={null}
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
向会话历史记录添加消息。
**请求**：
```protobuf theme={null}
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;
}
```
**响应**：
```protobuf theme={null}
message AddMessageResponse {
bool success = 1;
int32 history_size = 2;
StatusCode status = 3;
string message = 4;
}
```
***
### ClearHistory
清除会话消息历史记录。
**请求**：
```protobuf theme={null}
message ClearHistoryRequest {
string session_id = 1;
bool keep_context = 2; // Keep persistent context
}
```
**响应**：
```protobuf theme={null}
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）
```python theme={null}
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 参考](/cn/api/rest/overview)了解 HTTP 端点。
***
## 代码生成
从 .proto 文件生成客户端代码：
### Python
```bash theme={null}
python -m grpc_tools.protoc \
-I protos \
--python_out=. \
--grpc_python_out=. \
protos/**/*.proto
```
### Go
```bash theme={null}
protoc -I protos \
--go_out=. \
--go-grpc_out=. \
protos/**/*.proto
```
### TypeScript
```bash theme={null}
protoc -I protos \
--ts_out=. \
--grpc_out=. \
protos/**/*.proto
```
***
## 相关主题
HTTP REST 端点
流事件目录
Python 客户端库
数据持久化