Skip to content

Agent Mesh

clarify inference proxy behavior

Antonio Ojeaeb9b48260201
diff --git a/internal/node/inference_engine_test.go b/internal/node/inference_engine_test.go
index c26a0543..888d9b96 100644
--- a/internal/node/inference_engine_test.go
+++ b/internal/node/inference_engine_test.go
@@ -138,3 +138,24 @@ func TestInferenceService_Models_Uninitialized(t *testing.T) {
t.Fatal("Models: expected error for uninitialized service, got nil")
}
}
+
+func TestSingleJoiningSlash(t *testing.T) {
+ tests := []struct {
+ name string
+ a string
+ b string
+ want string
+ }{
+ {name: "root backend with /v1 path", a: "", b: "/v1/chat/completions", want: "/v1/chat/completions"},
+ {name: "slash backend with /v1 path", a: "/", b: "/v1/chat/completions", want: "/v1/chat/completions"},
+ {name: "prefix backend with /v1 path", a: "/proxy", b: "/v1/chat/completions", want: "/proxy/v1/chat/completions"},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ got := singleJoiningSlash(tt.a, tt.b)
+ if got != tt.want {
+ t.Errorf("singleJoiningSlash(%q, %q) = %q, want %q", tt.a, tt.b, got, tt.want)
+ }
+ })
+ }
+}
diff --git a/site/content/docs/user/agent-usage.md b/site/content/docs/user/agent-usage.md
index aad99904..e166debf 100644
--- a/site/content/docs/user/agent-usage.md
+++ b/site/content/docs/user/agent-usage.md
@@ -107,6 +107,13 @@ straight through untouched and is never used to authenticate to the node itself.
> proxy (`/sam/<peer>/...`) does **not** accept this fallback — there,
> `Authorization` is reserved exclusively for the destination's own credential.
+### OpenAI Facade & Inference Connectivity
+
+SAM nodes expose two ways for AI clients and OpenAI SDKs to interact with `type: inference` services across the mesh:
+
+1. **OpenAI Facade Interface (Recommended)**: Point standard OpenAI SDKs to `base_url="http://127.0.0.1:8080/v1"`. The facade aggregates available mesh models on `/v1/models` and handles seamless load balancing and failover for `/v1/chat/completions`.
+2. **Raw Egress Proxy Interface**: Power-users who want to explicitly route to a specific peer's inference backend use `/sam/{peer}/inference/{service}`. When targeting an OpenAI-compatible service via raw proxy, ensure `base_url` includes the explicit `/v1` namespace suffix (e.g. `http://127.0.0.1:8080/sam/{peer}/inference/{service}/v1`).
+
### Specific Integration Guides
Explore our step-by-step guides for integrating your node with popular agent clients:
* 🚀 **[Google Gemini AI Agent](../integrations/gemini.md)**: Connect using Python scripts and the google-genai SDK.
diff --git a/site/content/docs/user/node-configuration.md b/site/content/docs/user/node-configuration.md
index 1bd78044..7321500f 100644
--- a/site/content/docs/user/node-configuration.md
+++ b/site/content/docs/user/node-configuration.md
@@ -62,6 +62,13 @@ The `services` array allows you to register endpoints that remote peers in the S
| `env` | *(For MCP)* Key-value environment variables passed to the subprocess. |
| `target_url` | *(For HTTP/Inference)* The upstream local URL to proxy traffic to. |
+### Inference Service Path Standards & Proxy Routing
+
+When configuring `target_url` for `type: inference` services (e.g. Ollama, vLLM, OpenAI-compatible backends):
+* **Root Target URL Standard**: Always register `target_url` using the base root URL (e.g. `http://localhost:11434` or `http://localhost:8000`), strictly omitting `/v1`.
+* **OpenAI Facade Access**: Clients connecting via the node's local OpenAI Facade (`http://localhost:8080/v1`) request paths like `/v1/chat/completions`. SAM automatically proxies these to the backend's root URL.
+* **Raw Proxy Access**: If bypassing the Facade and making requests directly via the local egress proxy (`/sam/{peer}/inference/{service}`), the request path must include the explicit `/v1` namespace suffix (e.g. `http://localhost:8080/sam/{peer}/inference/{service}/v1/chat/completions`).
+
---
## 3. Defining Local Security (Target Attenuation)