A2 — Nexus

You do not need Nexus to build AgentRun. You need to know what it is, so that when the inference team says "call us through our Endpoint" you recognise the sentence, and so that the capstone defense can say precisely why the runtime does not use it yet.

What Nexus is

Nexus connects Temporal Applications across (and within) isolated Namespaces. Each team gets their own Namespace for security and fault isolation, while exposing a clean service contract for others to use through a Nexus Endpoint. Nexus is peer-to-peer, not hierarchical: caller and handler Workflows are siblings that communicate across Namespace boundaries. The point is separately owned Temporal applications calling each other through a contract, with the caller never learning the handler's Namespace, Task Queue, or implementation.

Services, Operations, Endpoints

A Nexus Service is a named collection of Nexus Operations that a team exposes. Operations abstract the underlying implementation: callers don't need to know whether an Operation starts a Workflow, sends a Signal, runs a Query, or executes other reliable code. Services are registered in a Worker that polls the Endpoint's target Task Queue, typically alongside the Workflows they abstract (the collocated pattern, the default) or in a dedicated router Worker on a "router" Task Queue that starts Workflows on other queues (the router-queue pattern, for independent scaling or different IAM permissions per fleet).

A Nexus Endpoint is a fully managed reverse proxy for Nexus Services. It routes requests from a caller Workflow to a target Namespace and Task Queue. Callers only need to know the Endpoint name. Endpoints live in the Nexus Registry, managed by UI, CLI, or API; adding one deploys it immediately.

Synchronous and asynchronous Operations

The Operation lifecycle supports two modes (limits as of 2026-09; see upstream page):

• Synchronous — completes within the 10-second handler deadline, as measured from the caller's Nexus Machinery. Use for Signals, Queries, Updates, or other reliable low-latency calls. Timed-out handlers are retried until the Operation's Schedule-to-Close timeout is exceeded.
• Asynchronous — starts a Workflow. Unlike a traditional RPC, an asynchronous Nexus Operation has an operation token that can be used to re-attach to a long-running Operation backed by a Workflow. Can run up to 60 days on Temporal Cloud.

Upstream's rule: use a synchronous Operation only when its complete execution path is highly reliable, has predictably low latency, and finishes well within the handler deadline; otherwise use an asynchronous one. An LLM call is therefore never a sync Operation.

Either way the caller's History records it: NexusOperationScheduled, then (async only) NexusOperationStarted, then NexusOperationCompleted or Failed, Canceled, or TimedOut. From the caller Workflow's point of view it is one awaited call, replayed like any other.

HTTP call versus Nexus Operation

  Service A ──HTTP──► Service B            Workflow A ──Nexus op──► Workflow B
                                            (ns: agent)             (ns: inference)
  retries:      yours                       retries:      Nexus Machinery, backoff
  timeout:      one socket                  timeouts:     Schedule-to-Close, Schedule-to-Start,
                                                          Start-to-Close, set by the caller
  B is down:    A fails or blocks           B is down:    A keeps the Operation scheduled;
                                                          it runs when B's Workers return
  record:       A's logs, maybe             record:       events in A's History, both sides linked
  cancel A:     B never hears               cancel A:     propagates to B's handler Workflow
  long work:    hold the connection         long work:    operation token; days are fine

The right-hand column is what "durable" buys you across a team boundary. The Nexus Machinery handles delivery with at-least-once execution: automatic retries with exponential backoff, rate and concurrency limiting, automatic load balancing, and circuit breaking, which trips after 5 consecutive retryable errors per caller-Namespace/Endpoint pair and probes again after 60 seconds (as of 2026-09; see upstream page). At-least-once means a handler may be invoked multiple times for the same Operation, so Nexus Operation handlers should be idempotent, similar to Activities. To deduplicate repeated handling, back the Operation with a Workflow whose Workflow ID is derived from the Operation's own identity and whose WorkflowIDReusePolicy is REJECT_DUPLICATE: a second delivery of the same Operation is refused rather than run twice. That deduplicates the Workflow start, which is not the same as exactly-once effects — the Activities inside still execute at-least-once, so an external effect still needs an idempotency key at its own boundary (module 4).

One asymmetry to remember: cancelling a caller Workflow propagates to its pending Nexus Operations and their handler Workflows, but terminating the caller abandons them. No cancel request is sent, the handler runs on with no signal that the caller is gone, and no compensation runs. Prefer cancellation.

The four-Namespace example

The place Nexus fits an AI platform is when the pieces are owned by different teams:

   ns: training          ns: inference          ns: evaluation
   ┌──────────────┐      ┌──────────────┐       ┌──────────────┐
   │ FineTune wf  │      │ Generate wf  │       │ Grade wf     │
   │ (hours–days) │      │ (seconds)    │       │ (minutes)    │
   └──────▲───────┘      └──────▲───────┘       └──────▲───────┘
          │ Endpoint            │ Endpoint              │ Endpoint
          │ "training"          │ "inference"           │ "evaluation"
          └──────────┬──────────┴───────────┬───────────┘
                     │                      │
                 ns: agent                  │
                 ┌──────────────────────────┴──┐
                 │ AgentRun wf  ── async op ──► │   each call: one awaited
                 │   fine_tune / generate /     │   Nexus Operation,
                 │   grade                      │   recorded in AgentRun's History
                 └─────────────────────────────┘

The agent team never sees the inference team's Task Queues or Worker fleet. If the inference Namespace's Workers are mid-deploy, AgentRun's Operation stays scheduled and completes when they are back. Handlers can chain: Workflow A → Nexus Op 1 → Workflow B → Nexus Op 2 → Workflow C, each step a separate durable Operation with its own retries.

The caller side in Python is small (names as of 2026-09; see upstream page):

from temporalio import workflow

@workflow.defn
class AgentRun:
    @workflow.run
    async def run(self, task: Task) -> Result:
        inference = workflow.create_nexus_client(
            service=InferenceService,            # @nexusrpc.service contract, imported
            endpoint="inference",
        )
        answer = await inference.execute_operation(
            InferenceService.generate,
            GenerateInput(prompt=task.prompt),
            schedule_to_close_timeout=timedelta(minutes=10),
        )

Know it exists; do not build the capstone on it

AgentRun's decomposition question — question 7 of the ten — is Activity or Child Workflow? Both live in one Namespace, both are in your labs' dev server today, and both are what the failure-injection suite exercises. Nexus answers a different question: whose Workflow is it? Reach for it when the callee is owned by another team with its own Namespace, deploy cadence, and access policy. Until that is true, a Nexus boundary adds an Endpoint registry, a second Namespace, cross-Namespace linking to debug, a circuit breaker that also trips when the handler fleet is simply scaled to zero, and the termination gotcha above — with nothing in return.

So for the capstone: one Namespace, Activities on lane-specific Task Queues (A1), ResearchAgent as a Child Workflow. In the defense, one sentence: "The inference and evaluation calls would become Nexus Operations the day those become other teams' Namespaces; the caller-side code shape is an awaited call, so AgentRun's loop does not change."

Where this is used

Lab 11.4 (labs/11-capstone-durable-agent-runtime/): the one-page architecture defense names the boundary where Nexus would enter and why it does not today, and question 10 — where Temporal ends and other systems begin — should place Nexus on the Temporal side of that line, at the Namespace boundary. Nothing in Labs 11.1–11.3 calls a Nexus Operation. If you want to see one run, the upstream Python Nexus quickstart works against the same dev server as the labs.