Skip to content

The only tool you need to know what is happening and how to fix it.

feat(devtesting-embedded): add OrcaRouter as a named chat gateway option (#295)

XiaoHuo888-huefa2b8e120ad9
diff --git a/examples/devtesting-embedded/README.md b/examples/devtesting-embedded/README.md
index 3d1372c0..91c8fb35 100644
--- a/examples/devtesting-embedded/README.md
+++ b/examples/devtesting-embedded/README.md
@@ -10,21 +10,28 @@ go run .
Then:
- App: http://localhost:8080/cdn (no build step) or http://localhost:8080 (requires `cd frontend && npm install && npm run build` first)
-- AI chat: http://localhost:8080/chat (needs `OPENROUTER_API_KEY` in `.env`)
+- AI chat: http://localhost:8080/chat (needs `ORCAROUTER_API_KEY` or `OPENROUTER_API_KEY` in `.env`)
- Dashboard: http://localhost:8082 — login `[email protected]` / `admin`
## AI chat (conversations, tool calls, sub-agents)
-`/chat` is a no-build chat UI backed by OpenRouter, built to exercise the AI conversation analytics end to end. Configuration lives in `.env` (gitignored):
+`/chat` is a no-build chat UI backed by an OpenAI-compatible gateway, built to exercise the AI conversation analytics end to end. Configuration lives in `.env` (gitignored):
```
-OPENROUTER_API_KEY=sk-or-...
-OPENROUTER_MODEL=anthropic/claude-sonnet-5
+# OrcaRouter (https://www.orcarouter.ai) — preferred; routing, fallback, guardrails
+ORCAROUTER_API_KEY=sk-orca-...
+ORCAROUTER_MODEL=orcarouter/auto
+
+# OpenRouter — fallback provider
+# OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_MODEL=anthropic/claude-sonnet-5
```
+When `ORCAROUTER_API_KEY` is set the chat routes through [OrcaRouter](https://www.orcarouter.ai) (`https://api.orcarouter.ai/v1`); otherwise it falls back to OpenRouter. It also runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes.
+
How it maps to Traceway:
-- Every LLM call emits a `gen_ai.*` span into the `Backend API` project, with real token counts and cost from OpenRouter usage accounting.
+- Every LLM call emits a `gen_ai.*` span into the `Backend API` project, with real token counts and cost from the gateway's usage accounting.
- The chat session id becomes `gen_ai.conversation.id`, so each browser conversation shows up on the Conversations tab. The persona picker sets `user.id` for the Users tab.
- The main **Support Chat Agent** has fake tools (`get_weather`, `lookup_order`, `get_server_time`) plus two delegation tools that run sub-agents in the same conversation: **Research Sub-Agent** (with `search_knowledge_base`) and **Math Sub-Agent** (with a real `calculate` evaluator). Each agent is a separate trace name on the AI Traces tab.
- Tool executions run in plain child spans (no `gen_ai.*` attributes) so they appear in the trace waterfall without inflating conversation turn counts; the tool calls themselves are parsed from the completion payloads.
diff --git a/examples/devtesting-embedded/ai.go b/examples/devtesting-embedded/ai.go
index dd321c1c..2fca4f27 100644
--- a/examples/devtesting-embedded/ai.go
+++ b/examples/devtesting-embedded/ai.go
@@ -19,17 +19,22 @@ import (
"go.opentelemetry.io/otel/trace"
)
-// An AI chat agent backed by OpenRouter, instrumented with gen_ai.* span
-// attributes so every LLM call lands in Traceway's AI Traces / Conversations
-// analytics: conversation grouping (gen_ai.conversation.id), per-user stats
-// (user.id), tool calls parsed from the completion payload, and sub-agents as
-// separate trace names inside the same conversation.
+// An AI chat agent backed by OpenRouter or OrcaRouter, instrumented with
+// gen_ai.* span attributes so every LLM call lands in Traceway's AI Traces /
+// Conversations analytics: conversation grouping (gen_ai.conversation.id),
+// per-user stats (user.id), tool calls parsed from the completion payload, and
+// sub-agents as separate trace names inside the same conversation.
+//
+// The provider is selected by environment: setting ORCAROUTER_API_KEY routes
+// through OrcaRouter (https://api.orcarouter.ai/v1), otherwise the agent falls
+// back to OpenRouter.
const openRouterURL = "https://openrouter.ai/api/v1/chat/completions"
+const orcaRouterURL = "https://api.orcarouter.ai/v1/chat/completions"
var aiHTTPClient = &http.Client{Timeout: 120 * time.Second}
-// --- OpenRouter wire types (OpenAI chat-completions compatible) ---
+// --- Gateway wire types (OpenAI chat-completions compatible) ---
type orToolCall struct {
Id string `json:"id"`
@@ -187,9 +192,15 @@ type toolEvent struct {
Result string `json:"result"`
}
-// callOpenRouter makes one chat-completions call and emits the gen_ai.* span
-// Traceway promotes to an ai_traces row.
-func (cc *chatContext) callOpenRouter(ctx context.Context, agent agentDef, messages []orMessage) (*orResponse, error) {
+// callGateway makes one chat-completions call and emits the gen_ai.* span
+// Traceway promotes to an ai_traces row. The gateway is selected by env:
+// ORCAROUTER_API_KEY routes through OrcaRouter, otherwise OpenRouter is used.
+func (cc *chatContext) callGateway(ctx context.Context, agent agentDef, messages []orMessage) (*orResponse, error) {
+ endpoint, apiKey, system := openRouterURL, os.Getenv("OPENROUTER_API_KEY"), "openrouter"
+ if os.Getenv("ORCAROUTER_API_KEY") != "" {
+ endpoint, apiKey, system = orcaRouterURL, os.Getenv("ORCAROUTER_API_KEY"), "orcarouter"
+ }
+
reqBody := orRequest{Model: cc.model, Messages: messages, Tools: agent.Tools}
reqBody.Usage.Include = true
@@ -207,18 +218,18 @@ func (cc *chatContext) callOpenRouter(ctx context.Context, agent agentDef, messa
attribute.String("gen_ai.conversation.id", cc.conversationId),
attribute.String("user.id", cc.userId),
attribute.String("gen_ai.operation.name", "chat"),
- attribute.String("gen_ai.system", "openrouter"),
+ attribute.String("gen_ai.system", system),
attribute.String("gen_ai.request.model", cc.model),
attribute.String("gen_ai.prompt", string(promptJSON)),
)
- httpReq, err := http.NewRequestWithContext(spanCtx, http.MethodPost, openRouterURL, bytes.NewReader(payload))
+ httpReq, err := http.NewRequestWithContext(spanCtx, http.MethodPost, endpoint, bytes.NewReader(payload))
if err != nil {
span.SetStatus(codes.Error, err.Error())
return nil, err
}
httpReq.Header.Set("Content-Type", "application/json")
- httpReq.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
+ httpReq.Header.Set("Authorization", "Bearer "+apiKey)
httpReq.Header.Set("X-Title", "traceway devtesting-embedded")
httpResp, err := aiHTTPClient.Do(httpReq)
@@ -237,15 +248,15 @@ func (cc *chatContext) callOpenRouter(ctx context.Context, agent agentDef, messa
var resp orResponse
if err := json.Unmarshal(body, &resp); err != nil {
span.SetStatus(codes.Error, err.Error())
- return nil, fmt.Errorf("openrouter returned non-JSON (%d): %.300s", httpResp.StatusCode, string(body))
+ return nil, fmt.Errorf("%s returned non-JSON (%d): %.300s", system, httpResp.StatusCode, string(body))
}
if resp.Error != nil {
span.SetStatus(codes.Error, resp.Error.Message)
- return nil, fmt.Errorf("openrouter error: %s", resp.Error.Message)
+ return nil, fmt.Errorf("%s error: %s", system, resp.Error.Message)
}
if len(resp.Choices) == 0 {
span.SetStatus(codes.Error, "no choices in response")
- return nil, fmt.Errorf("openrouter returned no choices (%d): %.300s", httpResp.StatusCode, string(body))
+ return nil, fmt.Errorf("%s returned no choices (%d): %.300s", system, httpResp.StatusCode, string(body))
}
completionJSON, _ := json.Marshal(map[string]any{"choices": resp.Choices})
@@ -271,7 +282,7 @@ func (cc *chatContext) runAgent(ctx context.Context, agent agentDef, userContent
messages = append(messages, textMsg("user", userContent))
for turn := 0; turn < agent.MaxTurns; turn++ {
- resp, err := cc.callOpenRouter(ctx, agent, messages)
+ resp, err := cc.callGateway(ctx, agent, messages)
if err != nil {
return "", err
}
@@ -530,14 +541,17 @@ type chatRequest struct {
}
func registerAIChatRoutes(router *gin.Engine, svc *otelService) {
- model := os.Getenv("OPENROUTER_MODEL")
+ model := os.Getenv("ORCAROUTER_MODEL")
+ if model == "" {
+ model = os.Getenv("OPENROUTER_MODEL")
+ }
if model == "" {
- model = "anthropic/claude-sonnet-5"
+ model = "orcarouter/auto"
}
router.POST("/api/ai/chat", func(c *gin.Context) {
- if os.Getenv("OPENROUTER_API_KEY") == "" {
- c.JSON(http.StatusServiceUnavailable, gin.H{"error": "OPENROUTER_API_KEY is not set; add it to examples/devtesting-embedded/.env"})
+ if os.Getenv("ORCAROUTER_API_KEY") == "" && os.Getenv("OPENROUTER_API_KEY") == "" {
+ c.JSON(http.StatusServiceUnavailable, gin.H{"error": "ORCAROUTER_API_KEY or OPENROUTER_API_KEY is not set; add it to examples/devtesting-embedded/.env"})
return
}
diff --git a/examples/devtesting-embedded/chat.html b/examples/devtesting-embedded/chat.html
index 9cc2ee47..647886af 100644
--- a/examples/devtesting-embedded/chat.html
+++ b/examples/devtesting-embedded/chat.html
@@ -82,7 +82,7 @@
<body>
<header>
<h1>AI Chat</h1>
- <span class="model" id="model">openrouter</span>
+ <span class="model" id="model">orcarouter</span>
<span class="spacer"></span>
<label class="session">user
<select id="persona">
diff --git a/examples/devtesting-embedded/main.go b/examples/devtesting-embedded/main.go
index 90b0768a..92828a82 100644
--- a/examples/devtesting-embedded/main.go
+++ b/examples/devtesting-embedded/main.go
@@ -137,7 +137,8 @@ func (s *otelService) log(ctx context.Context, sev otellog.Severity, sevText, bo
}
func main() {
- // OPENROUTER_API_KEY / OPENROUTER_MODEL for the AI chat live in .env.
+ // ORCAROUTER_API_KEY / ORCAROUTER_MODEL (or OPENROUTER_API_KEY /
+ // OPENROUTER_MODEL) for the AI chat live in .env.
_ = godotenv.Load()
go tracewaybackend.Run(
@@ -398,9 +399,9 @@ func main() {
fmt.Printf(" AI chat: http://localhost:%d/chat\n", appPort)
fmt.Println(" Dashboard: http://localhost:8082")
fmt.Println(" Login: [email protected] / admin")
- if os.Getenv("OPENROUTER_API_KEY") == "" {
+ if os.Getenv("ORCAROUTER_API_KEY") == "" && os.Getenv("OPENROUTER_API_KEY") == "" {
fmt.Println()
- fmt.Println(" WARNING: OPENROUTER_API_KEY is not set (.env) — /chat will not work")
+ fmt.Println(" WARNING: ORCAROUTER_API_KEY / OPENROUTER_API_KEY is not set (.env) — /chat will not work")
}
fmt.Println()
fmt.Println(" OTel logs test endpoints (hit with curl or browser):")