How Agent requests run

This reference is for Nexia maintainers who already have authorized access to the private host environment. Core is not distributed to external developers. These host commands are not prerequisites for the public CLI and cloud sandbox; start with the quickstart.

An Agent request begins with a bounded interpretation. It is not a database connection or general code execution, and most requests never enter analysis.

Request path

Intent, Router, and lane are separate controls. Core first restores delegated tenant, actor, session, and policy context, then reads the configured Primary-grade and fixed-role candidates; this preparation makes no model API call. A slash command supplies a deterministic intent. Ordinary prose requires the Router role model, which can classify, ask for clarification, or fail safely; valid signals cached for the same task are reused. An unknown slash command ends with its fixed command message. The lane router selects a primary lane and only needed supporting lanes, then exposes the exact permission- and policy-filtered palette. Only after that does Primary receive the palette and decide whether to call a tool.

The Router does not choose permissions, approvals, or code. A Router failure never falls back to Primary. A lane does not execute code; it withholds tools outside the current palette. The analysis tools are removed unless Gateway has both the analysis URL and token A.

Isolated analysis

Primary runs the user turn using its selected grade. Router is required for ordinary prose and never falls back to Primary. Analysis-worker and research-worker are optional fixed roles with their own configured candidates. The optional analysis-worker model can complete a small number of independent read-only evidence tasks; it is not the SQL/Python runtime. When Primary calls analysis.dataset.create, Core binds a lease to the tenant, actor, session, task, current authorization, and requested fields. analysis.run asks Core to authorize it, sends one sql or python operation to the controller, and Core validates the lease again before disclosure.

The local controller or analysis Worker receives only the Core-authorized export and starts a disposable sandbox. The sandbox has neither tenant credentials nor a general business-database connection. Core limits extraction to 10,000 authorized rows per dataset, 10 MiB across serialized envelopes, and 5,000 ms per extraction SQL statement. Controller limits cover input, output, sandbox time, memory, and capacity. A limit stops the execution; it does not make a partial export complete.

Clarification, routing failure, unavailable runtime, authorization rejection, capacity refusal, data or time limit, sandbox failure, cancellation, expiry, and result-publication failure stop safely. Results are size- and integrity-checked. Diagnostics do not disclose raw datasets, credentials, prompts, or controller exception text.

Central diagnostics

Central Admin → Agent → Analysis executions is read-only runtime diagnostics, not a cost ledger or a complete Agent trace. It records safe status, failure and limit classifications, available measurements, and tenant/session/task context. Agent usage remains a separate turn/attempt ledger; a related session or task does not assign the whole turn's model usage or cost to analysis.

Null means not collected, never zero. Timings can overlap and must not be summed. A row or byte observation at a limit is partial. A prepared or running row can be stale when terminal telemetry is delayed or missing, so it does not prove active work. Diagnostics retain records for 30 days.

Runtime configuration

Model assignment is managed in Central, not dotenv: Provider Keys holds provider credentials, Agent Grades assigns Primary candidates, and Agent Roles (/admin/agent-role-models) assigns ordered router, analysis_worker, and research_worker candidates. These assignments reference the model catalog through database relationships. Configure Router before ordinary prose requests.

The local root .env sets AGENT_ANALYSIS_URL=http://agent-analysis:8788, AGENT_ANALYSIS_TOKEN=local-agent-analysis-token, AGENT_ANALYSIS_CORE_URL=http://app:8000, and an empty AGENT_ANALYSIS_CONTROLLER_TOKEN. Compose gives URL/A to Gateway and A/Core URL/B to the controller. Generate a distinct local B before analysis; it has no usable default. task agent:restart rebuilds and restarts the local controller and runner.

Local controller setup

After task setup, generate B, then replace the existing analysis entries in .env; do not append duplicate keys. The values below are local development values, never production credentials.

openssl rand -hex 321

Paste that output into the existing dotenv block, then start the Agent profile:

AGENT_ANALYSIS_URL=http://agent-analysis:8788
AGENT_ANALYSIS_TOKEN=local-agent-analysis-token
AGENT_ANALYSIS_CORE_URL=http://app:8000
AGENT_ANALYSIS_CONTROLLER_TOKEN=<generated token B>
AGENT_ANALYSIS_CACHE_STORE=session12345

task dev:up:agent1

Use task agent:restart after controller, runner, or analysis environment changes; use task dev:up:core to return to the ordinary Core profile. Local controller settings have these defaults:

These are local controller inputs. The analysis Worker uses fixed Worker runtime limits rather than this local controller environment set; its Core dataset contract still observes the same Core dataset ceiling.

AGENT_ANALYSIS_CACHE_STORE is Core-owned and defaults to the shared, non-tenant-prefixed session store. Tests default it to array. Keep a persistent shared store for normal runtime operation so Core can restore the execution binding before tenant initialization.

A and B are distinct directional credentials. Gateway forwards only URL/A; B never reaches it. B reaches narrow Core analysis endpoints, while execution tokens and Core lease checks still bind export and disclosure to the current tenant, actor, session, task, and authorization.

First activation requires a released Core with the analysis routes, Central migration, and B installed before URL/A reaches Gateway. Production Deploy publishes the Core release tag and requests the Laravel Cloud deployment only. An operator deploys Analysis and Gateway from a reviewed checkout with Wrangler, passing the Core and Analysis URLs explicitly while preserving the configured Worker secrets. Deploy Analysis before Gateway when both change, then verify Worker versions, container image digests, and running instances. Laravel Cloud must separately hold matching Edge/Service/B values; JWT keys remain in Core. Health proves only authenticated Worker liveness, not Core B connectivity or a sandbox execution. An authorized analysis test after rollout supplies that evidence. Source and workflow configuration do not establish deployment. Rotate A at both Workers and B at Laravel Cloud plus the analysis Worker together.

Read the outcome

Enable the Agent Gateway covers Edge and Gateway. Environment Variables is the complete owner-indexed inventory. A Central diagnostic explains a recorded analysis outcome; browser streaming and model behavior still need a real authenticated turn.