跳转至

CONSUMERS

Flyto Agent 消费层一站式接入文档. 本文是 wrapper, 详细 API 契约见自动生成产物:

端口拓扑

cmd/common 单进程三 listener (signal handler 三路协调关闭):

端口 通道 协议 用途 host 暴露
9090 gRPC observation gRPC HealthService + SafetyChainService (verdicts / breakers) 否 (compose 内部)
8081 admin HTTP HTTP /admin/health / /admin/version / /admin/tenant + safetychain REST 镜像 否 (Caddy /admin/* 反代)
8080 business REST/SSE HTTP/1.1 + SSE /api/v1/* (engine.Run / engine.Session) 否 (Caddy /api/v1/* 反代)

外部入口 https://hub.flytoex.net 由 Caddy 按路径分流:

路径前缀 落地
/api/v1/* common:8080 (业务 REST/SSE; flush_interval -1, response_header_timeout 0)
/admin/* (非 proxy) common:8081 (admin HTTP)
/admin/proxy/* flyto-relay:7080 (basic_auth 临时, OIDC 替换中)
/swagger/* common:8080 (--swagger 启用时, auth bypass)
其他 logistics:8080 (C# WebAPI)

必填环境变量

变量 触发条件 示例 备注
ANTHROPIC_API_KEY --rest-addr 启用 (业务 REST 装配 anthropic provider) sk-ant-... dev / prod 都必填; 缺失 cmd/common log.Fatal 退出
FLYTO_PROXY_TOKEN flyto-proxy relay (HK-133 Phase 2-2a) 任意强随机 relay 内部 register endpoint auth
ADMIN_BASIC_AUTH_USER / ADMIN_BASIC_AUTH_HASH Caddy /admin/proxy/* 边界鉴权 yuanwei / bcrypt OIDC ready 后撤

CLI flag (cmd/common)

flag 默认 说明
--grpc-addr :9090 gRPC observation 监听
--http-addr 空 = disabled admin HTTP 监听; 空 = gRPC-only 形态
--rest-addr 空 = disabled 业务 REST/SSE 监听; 启用必带 ANTHROPIC_API_KEY
--cwd 进程 cwd engine Tool 执行根目录 (--rest-addr only)
--model claude-sonnet-4-6 engine 默认 LLM model id (见 ModelRegistry)
--oidc-issuer 空 = dev mode OIDC issuer URL; 空 = bypass auth (dev only); 生产必填
--oidc-audience 空 期望 OIDC audience
--oidc-tenant-claim tenant_id JWT tenant id claim 字段名
--version 空 健康响应回显的版本字符串
--swagger false /swagger/* 暴露 Swagger UI (--rest-addr only); auth bypassed

OIDC Auth 流程

客户端 ──(1)── IdP                      获取 access_token (aud = --oidc-audience)
   │
   │ Authorization: Bearer <token>
   ▼
hub.flytoex.net ──(2)── Caddy ──(3)── common:8080 / common:8081
                                      │
                                      ▼
                          server.authMiddleware
                                      │
                                      ▼
                       auth.HTTPMiddleware(verifier)
                          ├─ 验 OIDC 签名
                          ├─ 检查 audience
                          └─ 提取 tenant_id 注入 ctx
                                      │
                          通过 ──→ handler 执行
                          不通过 ──→ 401 Unauthorized

例外 allow-list (无需 token, 也不烧 rate-limit 预算):

  • GET /api/v1/health (liveness 探针)
  • OPTIONS /* (CORS preflight)
  • /swagger/* (UI 公开访问)

dev mode (--oidc-issuer 空): 全部 bypass, 启动日志 WARNING auth disabled (dev mode).

跨服务调用示例

业务 REST: 一次性 SSE 流式 Agent run

curl -N -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt":"你好"}' \
     https://hub.flytoex.net/api/v1/agent/run

Event 流 (named events, 见 server.go convertEvent):

event: text_delta
data: {"text":"你"}

event: turn_end
data: {"turn_number":1,"input_tokens":12,"output_tokens":3,"cost_usd":0.0001}

event: done
data: {"total_input_tokens":12,"total_output_tokens":3,"cost_usd":0.0001,"turn_count":1}

业务 REST: 多轮会话

# 创建
SESSION=$(curl -s -H "Authorization: Bearer $TOKEN" \
  -X POST https://hub.flytoex.net/api/v1/sessions | jq -r .session_id)

# 发消息 (SSE 流, 每次返回 assistant 增量)
curl -N -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"prompt":"继续"}' \
     "https://hub.flytoex.net/api/v1/sessions/$SESSION/messages"

# 关
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
     "https://hub.flytoex.net/api/v1/sessions/$SESSION"

观测 gRPC: SafetyChain verdicts

C# logistics 用 Grpc.Net.ClientFactory 调 SafetyChainService.ListVerdicts 拉取 Tool 装饰链产生的决策记录. 协议见 grpc-api.md SafetyChainService 段. cmd/common 当前 verdictStore 为空, 等行业 Tool 接入 safetychain.Assemble 后自动填充.

进一步阅读