Agentweaver

Appearance

Gateway ​

1–4. Goals, constraints, context and strategy ​

Use this page to understand how the Gateway exposes Agentweaver's owner services to browser and native CLI callers. The Gateway is a backend-for-frontend (BFF), not a workflow engine: the owner still decides whether a caller has current permission and whether a requested transition is valid.

It centralizes authentication, transport bounds and route discovery without centralizing domain decisions. Owners remain responsible for current authority and valid transitions. Retained MCP compatibility code can consume the same OpenAPI; it is not a supported product surface.

5. Building blocks ​

How Gateway routes requests ​

Gateway authenticates the caller, selects a configured owner, forwards the request, and returns the owner's result. A finite route catalog maps public /api/v1 operations to Projects & Config, Orchestrator, Knowledge, Events, or Identity Broker.

SourceResponsibility
GatewayRouteCatalog.csMaps public routes to owner routes and forwarding rules
GatewayOptions.csConfigures fixed HTTPS owner roots, web origin, audience, issuer, and timeout
GatewayOwnerClient.csForwards the caller request, bounds responses, and handles server-sent events (SSE)
GatewayEndpoints.csImplements health, discovery, BFF connection flows, and fallback behavior
GatewayOpenApi.csBuilds OpenAPI from the route catalog
GatewayRunEventProjection.csValidates public event pages and envelopes
GatewayWebCors.csApplies exact-origin, route-specific browser policies
Program.csComposes authentication, clients, CORS, telemetry, and routes

The browser callers and Broker session handling live in apps/web/src/v1/api.ts and AuthContext.tsx.

6. Runtime view ​

Understand the route boundary ​

The route catalog declares each operation's method, owner path, operation ID, body behavior, and forwarding flags. Callers cannot choose an upstream URL. Unknown versioned paths reach the authenticated route_not_found fallback instead of an arbitrary proxy.

GET /openapi/v1.json publishes this finite API contract for discovery clients. The retained MCP adapter also reads it to build its source tool catalog. Health and OpenAPI discovery are anonymous; product operations require authentication.

GET /agents/agentweaver.agent.md is also anonymous. It returns the operator agent definition that is embedded in the Gateway assembly, so it needs no owner call. The route is excluded from the OpenAPI document; otherwise the MCP service would turn a file download into a tool. A test compares the embedded copy with .github/agents/agentweaver.agent.md and compares the definition's tool map with the MCP-admissible OpenAPI operations, so both copies must change together when tools are added or removed.

OpenIddict validates the configured Identity Broker issuer and audience. Before forwarding, the proxy requires one current validated bearer and forwards it unchanged. X-Agentweaver-Tenant selects a tenant for owner validation; it is not a role or identity assertion. Supported idempotency and revision headers are forwarded, not interpreted as approval.

Project-wide Knowledge search is the explicit GET /api/v1/projects/{projectId}/knowledge/records route. It requires an unbound Broker token; the Knowledge owner checks current project AccessPrivateKnowledge authority for the project or its tenant and reads only existing Memory selections through its private Knowledge-selection route. Gateway does not add an arbitrary proxy path or make the authorization decision.

The canonical Platform Policy read, validate, and write operations are also fixed catalog routes. The Gateway forwards the optional tenant selector and exposes Cache-Control; each route has a 5 MiB response limit, and the two body routes have a 5 MiB request limit. All three are excluded from MCP. Projects & Config owns authorization, validation, and policy state. See the Policy API contract.

Gateway preserves the owner's response status and body. In particular, 202 Accepted means an owner accepted an operation; it does not prove that a resource, model turn, or workflow finished. Gateway has no domain database and does not reconstruct current state from a cached response.

Coordinator root Host replacement is an Orchestrator-owned operation. Gateway forwards its saved status and receipt; callers must read the same operation until it is terminal instead of treating an accepted or pending response as completion.

Follow a catalog request ​

Before calling a product route, obtain a valid Broker bearer and use a catalog operation with its declared method, path, and body.

  1. Routing selects the finite endpoint and browser CORS policy.
  2. Authentication and authorization run before the owner call.
  3. GatewayOwnerClient expands and escapes route values against the saved owner path.
  4. The client forwards the original bearer, allowed selectors and headers, query string, and declared JSON body.
  5. A per-request deadline bounds the owner call and response read.
  6. The proxy returns the owner's status, supported headers, and bounded body with Cache-Control: no-store.

The default request-body limit is 64 KiB. Catalog entries override it for specific operations, including skill content and Knowledge import. Ordinary owner responses are limited to 8 MiB, and redirects are rejected. See the Gateway/BFF guide for operation-specific limits.

Validate owner TLS ​

Gateway uses RuntimeOwnerHttpTransport.CreateTrustedOwnerHandler() for its internal owner clients. The handler trusts only the read-only service-backend-ca mount and checks the owner hostname, certificate validity, and server-authentication purpose. The public Broker issuer remains on normal system trust for token discovery.

GET /api/v1/authorization/context uses a dedicated path. Gateway validates the Projects response's no-store header, exact contract shape, caller scope, and confirmed tenant context. It does not create membership or derive permissions from a selector.

Understand sign-in and connection flows ​

Identity Broker owns browser sign-in. Gateway's explicit BFF routes support GitHub Repo App, Hosted Copilot, and remote MCP connection management. These fixed routes are not general callback proxies. Their forwarders enforce the relevant query, cookie, tenant-selector, and response contracts.

A connection reference identifies a connection; it is not a provider credential. For browser requests, Gateway:WebOrigin identifies one exact HTTPS origin. The Copilot connection BFF uses a credentialed cookie policy; ordinary versioned API policies do not enable ambient credentials.

Follow a journal-backed event stream ​

The public SSE path reads committed Events pages rather than forwarding an unverified upstream stream. You need current run-bound project read access and an opaque journal cursor if you are reconnecting.

  1. Gateway reads the cursor from cursor or Last-Event-ID. If both are present, their values must match.
  2. It checks current run-bound project read access through Projects.
  3. It reads and validates a bounded Events page.
  4. It checks project access again before each event write.
  5. It emits event: session-event, the opaque cursor as id, and the projected JSON envelope as data.
  6. When no event is available, it flushes a keep-alive and polls again.

The projection checks event schema, ordering, references, and cursor progress. It excludes private runtime configuration and remote-tool result material. Reconnect resumes journal history; it does not trigger model execution. The configured owner timeout applies to each owner request, not to the entire long-lived SSE connection.

Diagnose failures ​

ConditionGateway behavior
Missing, invalid, or expired bearerReturns 401
Owner rejects permission or a state transitionPreserves the owner's status and body
Owner redirects or is unavailableReturns 502
Owner response violates its validated contract or size boundReturns 502; aborts if the response already started
Owner request reaches its deadlineReturns 504
Invalid reconnect cursorReturns 400 before streaming starts
Authority or owner access fails during SSEAborts the stream to prevent further disclosure

Retry or reconnect according to the owner contract. Gateway does not retry a mutation as a new operation or infer success after a broken connection.

7–9. Deployment, shared concepts and decisions ​

Gateway is a shared HTTPS service with configured owner roots, not an agent inside a Sandbox. Browser CORS requires one exact Web origin. Internal owner trust uses the backend CA; public issuer discovery uses system trust. The deployment view maps workloads and routing.

Current project authority follows Projects; Identity owns sign-in, and Events owns the history projected into SSE. The canonical decision links retain their actual statuses; route presence does not establish support or live availability.

10–12. Quality, risks and glossary ​

Context and stimulusResponse and measureVerification state
An authenticated caller requests an unknown versioned routeReturn route_not_found; no arbitrary upstream requestGateway route/proxy tests
Projects denies read access during SSEStop further event disclosure and abort the streamControlled authorization/stream tests
An owner response exceeds its bound or redirectsReturn 502, or abort an already-started responseControlled owner-response tests; not live TLS proof

Gateway availability depends on the selected owner. Retrying a broken mutation connection as a new operation risks duplicate effects; callers must use the owner's idempotency/reconciliation contract.

Terms: BFF means backend-for-frontend; SSE is a server-sent event stream; an owner result is domain status, not a Gateway inference of completion.

Related content ​