@gea-ai/agent-sdk 0.1.260917-alpha.2 → 0.1.260920-alpha.0

package/README.md

@@ -13,7 +13,167 @@ for validation, Studio display, and exact-version execution. Snapshots never
 contain handler functions, credentials, Connector Connections, tenant identity,
 provider configuration, or environment values.
 
-## Tenant application authentication
+## Tool outputs
+
+`defineTool` accepts `outputSchema` (Zod) and synchronous or asynchronous
+`toModelOutput({ toolCallId, input, output })`, following AI SDK's separation
+between the result used by the application and the result shown to the model.
+Both server and client tools retain output types in `InferAgentUITools`.
+
+`outputSchema` is a declaration/type hint. It never parses, coerces or validates
+returned data, including client-supplied results. It is serialized in the Agent
+snapshot and sent as each function's `output_schema` for OpenAI Responses.
+Completions and Anthropic do not receive that field. This does not configure the
+Agent's final structured response. When a converter changes a JSON wire output,
+the author must keep the Responses output schema appropriate for that output.
+
+For multimodal results, enable the Agent's `artifacts` capability. Both implicit
+and explicit persistence use the same request-time Artifact resolution:
+
+- Implicit: return typed `file` parts from `toModelOutput` containing a URL,
+  base64 string or bytes. The SDK uploads them and persists Artifact IDs.
+- Explicit: save the file through `ctx.artifacts`, then return an existing ID
+  from `execute` and reference it in `toModelOutput`; no second upload occurs.
+
+For example, the implicit converter can map an ordinary business result:
+
+```ts
+toModelOutput: ({ output }) => ({
+  type: "content",
+  value: [
+    {
+      type: "file",
+      mediaType: "image/png",
+      filename: "plot.png",
+      data: { type: "url", url: new URL(output.url) },
+      // Or: data: { type: "data", data: output.base64 }
+    },
+  ],
+});
+```
+
+The explicit converter can reference a scoped Artifact:
+
+```ts
+const viewPlot = defineTool({
+  name: "viewPlot",
+  description: "Show a saved plot to the model.",
+  input: z.object({ artifactId: z.string().uuid() }),
+  outputSchema: z.object({ artifactId: z.string().uuid() }),
+  execute: async ({ artifactId }, ctx) => {
+    const { artifact } = await ctx.artifacts!.get({ id: artifactId });
+    return { artifactId: artifact.id };
+  },
+  toModelOutput: ({ output }) => ({
+    type: "content",
+    value: [{ type: "artifact", artifactId: output.artifactId }],
+  }),
+});
+```
+
+`AgentToolModelOutput` supports AI SDK text/JSON/error outputs and content with
+text, modern tagged `file` parts, or `{ type: "artifact", artifactId }` parts.
+Inline or URL file parts are uploaded through the existing Artifact upload
+capability; provider-specific file IDs must first be saved as GEA Artifacts.
+Model context retains immutable IDs and descriptive metadata. Authorized
+download URLs are resolved only when preparing a model request. Replaying saved
+tool results reuses their conversion instead of uploading the same media again.
+Tool calls already removed by context compaction are not reconstructed from UI
+history during approval or client-tool continuation. Large-result offloading
+replaces only text; the model-facing file references remain attached.
+Keep the original `execute` result JSON-serializable; the converter does not
+replace the UI result with its model-facing content.
+Model-facing `error-text` and `error-json` remain errors in both engines without
+changing the original successful UI result into an execution failure.
+
+Media placement is a model capability, not a protocol inference. Configure
+`targets["provider/model"].supportsMultimodalToolOutput` in Catalog v2: `true`
+keeps supported media inside tool results; `false` or omitted keeps text/Artifact
+IDs in the tool result and adds media in a user message after all results from
+that tool-call batch. This applies independently of API format. The chosen
+model must still support the supplied image/file media type in user messages;
+fallback cannot add vision to a text-only model. The Completions native adapter
+currently supports image blocks. Both the default
+Agent Core engine and `aiSdk()` use these rules. Rebuild the Agent bundle to
+adopt the new runtime behavior.
+
+## Calling the Agents HTTP API
+
+Call the public `/api/v1` API with ordinary HTTP and a fixed Agent ID. No Agent
+SDK dependency is required for API callers:
+
+```ts
+const baseUrl = "https://<tenant-host>/api/v1";
+const headers = {
+  authorization: `Bearer ${projectApiKey}`, // Or a user OAuth token.
+  "content-type": "application/json",
+};
+const created = await fetch(`${baseUrl}/sessions`, {
+  method: "POST",
+  headers,
+  credentials: "omit",
+  redirect: "error",
+  body: JSON.stringify({ agent_id: agentId, environment: "production" }),
+});
+if (!created.ok) throw new Error(`Session creation failed: ${created.status}`);
+const session = await created.json();
+const response = await fetch(`${baseUrl}/sessions/${session.id}/runs`, {
+  method: "POST",
+  headers,
+  credentials: "omit",
+  redirect: "error",
+  body: JSON.stringify({ input: "Hello", stream: true }),
+});
+if (!response.ok) throw new Error(`Run admission failed: ${response.status}`);
+// Consume response.body as the API's SSE stream.
+```
+
+Project Key access to deployed project Agents does not require OAuth or store
+publication. OAuth access remains subject to user and tenant authorization.
+For local development, use the CLI's separate API listener, omit authorization
+and omit `environment` so the local API selects it. Shared HTTP schemas live in
+`@gea-ai/contract/agent-http-api`; routes are documented by `/api/v1/openapi.json`.
+
+Read `GET /sessions/{id}` for `active_run`, capture that Run ID, then observe
+`GET /runs/{id}` or its stream. A later Run in the same Session does not change
+the captured invocation. Cancellation acknowledgement is separate from final
+cleanup. Aborting an HTTP request does not cancel a Run; a lost POST response
+does not establish whether it was accepted, so do not automatically replay it.
+
+The authoring SDK owns Agent execution. An Agents API client SDK is deferred.
+The Worker `AGENTS.fetch` binding is an authenticated HTTP transport using the
+same paths, payloads and responses. It does not introduce `agents.*`, `sessions.*`
+or `runs.*` client methods. See the
+[HTTP integration guide](https://musegea.com/developers/agent-api).
+
+## Custom Agent execution URL
+
+```ts
+export default defineAgent({
+  name: "Support",
+  slug: "support",
+  model: "your-model",
+  http: { runPath: "/gea/support-entry" },
+});
+```
+
+`http.runPath` selects the Agent's actual Worker execution route. Omission uses
+`/gea/agents/<key>/run`. The route belongs to the immutable snapshot and manifest;
+changing it does not change the Agent ID. Hosts invoke the recorded version's
+route, including retained child Runs. OPTIONS reports the declared route without
+creating a Session. Build/upload validation probes it and rejects mismatches and
+conflicting declarations. Private Session control endpoints keep their standard
+protocol paths.
+
+Agents API dispatches **to** this Worker route. The existing public authentication
+adapter is still present; removing its control-plane round trip is unfinished.
+This increment does not change `http.auth` behavior or add an API client SDK.
+
+## Existing Worker URL authentication
+
+The following Worker URL adapter remains available while the unified Agents API
+migration proceeds. `StudioAgentClient` is still used by existing Worker handlers;
+it is not the fixed-ID `/api/v1` interface above.
 
 Agent HTTP accepts Project API keys and GEA user OAuth tokens by default. Push the
 Worker and associate the Agent with its app in **Studio → Applications**. Publish
@@ -34,26 +194,13 @@ approval for external test tenants and explicit environment enablement. The
 application starts standard OAuth; GEA confirms the actual user and consumer tenant
 and resolves the installation internally. Do not send an installation ID.
 
-```ts
-import { StudioAgentClient } from "@gea-ai/agent-sdk/studio-server";
-
-const agent = new StudioAgentClient({
-  api: copiedEnvironmentUrl, // The copied /run URL is accepted directly.
-  token: currentUserAccessToken,
-});
-const response = await agent.run({ message: "Hello" });
-```
-
-The token identifies the user, app and tenant; the URL selects the environment
-and Agent. Users need current consumer tenant membership and application authorization.
-Their configuration, Connections, Chats, files and traces belong to that environment
-installation. Existing Chat/Run calls retain their pinned execution version;
-historical Workspace-bound records still require access to that Workspace.
-
-`projectKeyAuth()` and Project API Keys retain Studio development access. `token`
-accepts either credential, subject to the Agent's declared auth; a Project Key does
-not represent a tenant user or grant cross-tenant installation access. There is no
-third marketplace URL. Standalone Worker OAuth publication remains future work.
+Use direct HTTP against platform `/api/v1/sessions` and
+`/api/v1/sessions/{sessionId}/runs`, with a Bearer Project API Key or OAuth user
+token and the canonical Agent ID. Project Keys retain Project service scope;
+OAuth tokens resolve the current user and tenant installation. Neither changes
+the Agent's default host-context execution policy. The older `studio-server`
+client targets the retired Worker credential entry and should not be used for
+new integrations.
 
 ## Agent Authoring Shapes
 
@@ -175,64 +322,28 @@ Generated code uses `createAgentApplicationFetch()`, which owns:
 /gea/agents[/<agentKey>]/sessions/<sessionId>/v1/<operation>
 ```
 
-Hosted Agent HTTP handlers accept Project API keys and platform user tokens by
-default, equivalent to this explicit configuration:
+Agent execution requires trusted host invocation context by default. Public
+Agents API accepts Project API Keys and OAuth user tokens, checks their scope,
+and admits the Session/Run before calling this Worker's configured execution URL.
+The Worker does not authenticate those credentials again.
 
 ```ts
-import {
-  defineAgent,
-  projectKeyAuth,
-  platformUserAuth,
-} from "@gea-ai/agent-sdk";
+import { defineAgent } from "@gea-ai/agent-sdk";
 
 export default defineAgent({
   name: "support",
   slug: "support",
   model: "gea-model-1",
-  http: { auth: [projectKeyAuth(), platformUserAuth()] },
+  http: { runPath: "/gea/support-entry" },
 });
 ```
 
-Set `auth: projectKeyAuth()` or `auth: platformUserAuth()` to accept only that
-credential type. Explicit configuration replaces the default; it never appends
-the other built-in method. Key calls retain Project ownership, while user tokens
-require application installation admission and keep the consumer's installation
-ownership. The two identities and permissions are never combined. These rules
-apply to Agent routes; ordinary routes in `worker.ts` retain their own authentication.
-
-```ts
-// Inside defineAgent(...):
-http: {
-  auth: false;
-} // Explicit public access to this Agent's HTTP API.
-```
-
-An application can replace the default with its own Session authenticator:
-
-```ts
-http: {
-  auth: async (request, { environment }) => {
-    const session = await getSession(request, environment); // Your verified session.
-    return session
-      ? { principalType: "user", principalId: session.userId }
-      : null;
-  },
-}
-```
-
-An authenticator returns a verified platform authorization, an external user,
-a `Response`, or `null`. An array runs in order: `null` means this method does
-not apply, while an identity or any `Response` stops the chain. An empty array
-or a chain that returns only `null` rejects with 401. Exceptions stop the chain
-and become an HTTP 500 at the Agent boundary. Built-in methods recognize their
-credential prefix before validation; malformed, revoked or denied credentials
-and service failures never fall through to another identity. Custom methods
-should likewise return an error `Response` for invalid credentials, reserving
-`null` for a method that does not apply. A single custom authenticator returning
-`null` still rejects with 401. Project Keys stay on the backend; they never
-represent the creator's GEA user.
-`authenticateProjectKey(request, environment.PROJECT)` also works in ordinary
-Worker routes with a declared Project binding and a Project attachment.
+Omit `auth` for normal hosted execution. Set `http: { auth: false }` only when
+this Agent's Worker HTTP entry should also admit anonymous requests. The host
+still registers their Session/Run with project-scoped anonymous ownership.
+Request headers and bodies cannot supply a trusted principal or parent Run.
+This setting does not disable public Agents API Key/OAuth checks or expose
+private Session controls. Ordinary business routes keep their own authentication.
 
 `OPTIONS /gea/agents/<agentKey>/run` returns only the Agent key, canonical run
 path and HTTP protocol version. It runs before authentication and does not
@@ -272,11 +383,12 @@ credential or target configuration.
 
 ## Context strategies
 
-Agents use the existing tool-output offload and rolling summary by default.
-Configure that recipe with `defaultContext`, replace it with a custom strategy,
-or set `context: false` to disable automatic summaries, file writes and tool-result
-replacement. Disabling compression preserves already committed summaries and
-continues normal message persistence.
+Tool-output offload and context summarization are independent features. Offload is
+on by default, including with a custom or disabled context strategy. Configure it
+on `defineAgent`, or set `toolOutputOffload: false` to keep future outputs inline.
+Use `context: false` to disable automatic summaries and context callbacks; set
+both switches to false to disable both features. Already committed summaries and
+offload references remain readable.
 
 ```ts
 import { defineAgent } from "@gea-ai/agent-sdk";
@@ -286,30 +398,68 @@ export default defineAgent({
   name: "assistant",
   slug: "assistant",
   model: "gea-model-1",
+  toolOutputOffload: {
+    offloadAtCharacters: 4_000,
+    replaceAtCharacters: 8_000,
+    preserveRecentGroups: 5,
+  },
+  sessionTools: true,
   context: defaultContext({
-    toolOutput: { offloadAtCharacters: 4_000, replaceAtCharacters: 8_000 },
     preserveRecentGroups: 5,
-    summarization: {
-      triggerAtTotalTokens: 64_000,
-      // Optional: model, instructions, maxOutputTokens.
-    },
+    summarization: { triggerAtTotalTokens: 64_000 },
   }),
 });
 ```
 
-`toolOutput: false` and `summarization: false` independently disable the two
-parts of the default recipe. Thresholds use model-visible characters and the
-last provider-reported `usage.totalTokens`; the SDK does not estimate tokens.
-Recent groups keep tool calls and their results together. Without Computer
-storage, tool outputs are saved in the chat's AgentSession and retrieved with
-`readToolOutput` using a SHA-256 id and bounded character ranges. Computer-enabled
-Agents retain their file-backed `readFile` retrieval. Offload runs before tool
-results enter a persisted model projection; complete UI messages and events
-remain available separately.
+Offload thresholds use model-visible characters. Results at the first threshold
+are stored; those at the replacement threshold are immediately stubbed. Smaller
+stored results remain inline in recent message groups; `preserveRecentGroups: 0`
+replaces them immediately. The default summary strategy also releases recent-group
+protection under its token-pressure threshold. Summary thresholds use the last
+provider-reported `usage.totalTokens`, without token estimation.
+
+All newly offloaded results live in the AgentSession, independent of Computer.
+The SDK automatically supplies `readToolOutput` with a SHA-256 id and bounded
+character ranges. Its bounded output is not offloaded again. Offload happens
+before model-projection persistence, while the UI transcript retains full results.
+Existing file-backed references retain their original retrieval instructions.
+The reader remains available when a Session has stored offloads even if future
+offloading is disabled.
+
+The old `defaultContext({ toolOutput: ... })` option remains a deprecated fallback;
+an explicit `toolOutputOffload` setting takes precedence. Old snapshots without the
+new field retain their context-owned policy. Rebuilding an Agent with `context:
+false` now requires `toolOutputOffload: false` as well to disable both features.
+
+### Built-in model tools
+
+- `sessionTools: true` adds `sessionList`, `sessionRead`, and `sessionSend`.
+  It defaults to false. The old `chatList()` / `chatRead()` / `chatSend()` selections
+  remain deprecated compatibility inputs; an explicit `sessionTools` setting
+  replaces them. All three tools use Agents API in hosted and local execution:
+  `sessionList({agentId?, cursor?, limit?})` lists accessible Sessions;
+  `sessionRead({sessionId, cursor?, limit?})` reads saved messages;
+  `sessionSend({sessionId, message, mode?})` sends inbox input (default `follow_up`).
+  List/read return `{items, next_cursor}`; send returns `{id, session_id, duplicate}`,
+  acknowledging delivery rather than Run completion. A Session needs a prior Run
+  before messaging. Identity and environment come from the current Run; Key service
+  principals do not need a workspace user and OAuth retains tenant/user isolation.
+- Declaring private or referenced subagents adds `agent`, `runWait`, and
+  `runCancel` when the host admits those targets. The existing `agentTool()`
+  selection enables root self copies. Ordinary Agents do not gain Run tools just
+  because they run in an inbox. Implicit joins and descendant cleanup remain
+  runtime behavior and do not depend on model tool visibility.
+- Offload adds `readToolOutput` automatically; do not declare it in `tools/`.
+
+`gea agent validate` reports `builtinTools`, including each tool's source feature.
+Generated message types include these tools. Reserved generated names are checked
+during packaging. This inventory describes configured tools; host authorization
+and dynamic Connector discovery are still resolved at runtime. Internal managed
+operation IDs remain compatible with the existing host protocol; the model-facing
+names above are camelCase.
 
 A custom strategy is an object with optional `prepareStep`, `onStepEnd` and
-`onEnd` callbacks, using the AI SDK 7 names. These callbacks replace the default
-recipe. `prepareStep` receives durable `messages`, `contextSize`, `stepNumber`
+`onEnd` callbacks, using the AI SDK 7 names. These callbacks replace the summary strategy, independently of offload. `prepareStep` receives durable `messages`, `contextSize`, `stepNumber`
 and `runtimeContext`; returning `{ messages }` replaces the active projection
 for subsequent steps and Runs. Returning nothing keeps it. `onStepEnd` also
 receives that step's `usage` and `finishReason`; `onEnd` receives the main loop's
@@ -640,7 +790,7 @@ override to the public `/run` API or Studio composer. See the upstream
 [OpenAI](https://ai-sdk.dev/providers/ai-sdk-providers/openai) and
 [Anthropic](https://ai-sdk.dev/providers/ai-sdk-providers/anthropic) options.
 
-## Background Agent tasks
+## Agent delegation through Sessions and Runs
 
 Declare private definitions in `subagents/<name>/agent.ts` with their own `AGENTS.md`, tools, skills and connectors. They run in independent Sessions and may declare further subagents. Only top-level definitions become public Worker entrypoints.
 
@@ -649,18 +799,51 @@ References are explicit default exports from `subagents/<alias>.ts`:
 ```ts
 import { defineAgentReference, defineRemoteAgent } from "@gea-ai/agent-sdk";
 
-// Same Worker: slug is checked against the CLI-generated WorkerAgentRegistry.
+// Same Worker, checked against the generated WorkerAgentRegistry.
 const sales = defineAgentReference({
   slug: "sales",
   description: "Sales analysis",
 });
-// Same Project: uses the Studio Agent slug and the caller's environment.
+
+// Same Agents API: the host revalidates the calling Run's authority.
 const legal = defineRemoteAgent({
-  slug: "legal-advisor",
+  agentId: "bb141b12-6f63-43bd-8ab6-77930916d3ef",
   description: "Legal review",
+});
+
+// Another service: use its API root and canonical Agent ID.
+const external = defineRemoteAgent({
+  agentId: "34910649-2df7-4978-8794-8d8fb72f16cd",
+  url: "https://legal.example.com/api/v1",
+  environment: "production",
+  description: "External legal review",
+  auth: { bearerTokenEnv: "LEGAL_AGENT_KEY" },
+});
+```
+
+Each reference file default-exports one reference. All targets use `agent({ target: "alias", message, sessionId? })` and return `{ status: "working", runId, sessionId }`. Callers only see their own declared aliases. Include `agentTool()` in the root's tools to allow self copies by omitting `target`; children cannot create unnamed copies.
+
+Use `runWait({ runIds, timeoutMs? })` to wait for specific Runs and `runCancel({ runId })` to request cancellation. The SDK owns waiting, batched parent wakeups and descendant cleanup. Cancellation acceptance is not completion. A logical Run keeps its ID through normal waits and resumptions; continuing an idle child with the same target and `sessionId` creates a new Run. There is no Task resource or progress-reporting tool.
+
+Remote references always use the canonical Agent ID, optionally with another service's API root. Their Session and Run IDs come from that API. Remote transport creates Sessions/Runs and reads status, messages and cancellation through ordinary HTTP; it never calls a Worker's `/gea/xxxx` execution URL directly. The API selects the versioned Worker route. A remote reference without `environment` inherits the invocation environment (`local` in CLI development).
+
+Same-service calls inherit live Project Key or OAuth authority through a short-lived, host-only signed context. Studio host calls use a Project service scope isolated by Worker, environment and principal. Explicit credentials override inherited authority. Calls to another API origin use only explicitly configured credentials; they never forward the parent's bearer. Knowing an Agent ID does not grant access. Same-service parent links are registered by the host; cross-service relationships live in the parent Session and point to the actual remote IDs.
+
+Remote observation survives parent waiting using the existing Session pending-dispatch mechanism. A transport error does not invent a terminal outcome, and accepted Run creation is never automatically replayed. Host shutdown stops observation without cancelling remote execution. General crash recovery and approval continuation remain separate lifecycle work.
+
+Upgrade SDK, CLI, server and Worker Runtime together and rebuild immutable bundles. The physical `AGENT_TASK_SESSIONS` namespace remains to preserve existing child Session history; it no longer represents Tasks.
+
+## Fetch-style Agents binding
+
+Generated Agent Workers include an `AGENTS` binding. Other Workers can declare `{ name: "AGENTS", type: "agents" }` in their bindings. It exposes the same HTTP paths and payloads, without a separate API client SDK:
 
+```ts
+const response = await env.AGENTS.fetch("/api/v1/agents?limit=20");
+const agents = await response.json();
 ```
 
+Within a trusted Agent invocation, the host supplies signed invocation authority. An ordinary hosted Worker invocation without a source Run must provide its Project API Key or OAuth token in `Authorization`. Local development uses the local API's existing authority. The binding does not expose host signing secrets or permit arbitrary destinations. Default host authority covers Agents, Sessions and Runs; File, Connector and Computer operations require explicit credentials with their existing grants.
+
 ## Call a Studio Agent with AI SDK
 
 Use `StudioAgentChatTransport` from `@gea-ai/agent-sdk/studio-client` with
@@ -708,22 +891,8 @@ const agent = new StudioAgentClient({
   api: env.GEA_AGENT_API_URL, // Agent base URL without /run.
   token: env.GEA_PROJECT_API_KEY,
 });
-// URL: a GEA Agent protocol endpoint. The key stays in runtime environment configuration.
-const external = defineRemoteAgent({
-  url: "https://legal.example.com/gea/agents/advisor",
-  description: "Legal review",
-  auth: { bearerTokenEnv: "LEGAL_AGENT_KEY" },
-});
 ```
 
-Each reference file default-exports one reference. All targets use `agent({ target: "alias", message, agentId? })`; callers only see their own declared aliases. Include `agentTool()` in the root's tools to additionally allow self copies by omitting `target`. Named delegation follows each node's own declarations; child invocations cannot create another unnamed copy.
-
-The tool returns `{ status: "working", taskId, agentId }`. `task_update({ message })` reports progress, and `task_cancel({ taskId })` requests cancellation. The host continues idle parent conversations when updates arrive. A child task finishes after its descendants and notification inbox settle, including any final summary turn. Continue an idle child with its returned `agentId` and the same target.
-
-URL targets implement GEA task create/status/cancel endpoints. New calls and continuations follow the deployment selected by the URL, retaining history while using its current model, instructions and tools. Accepted tasks finish on their selected version. URL credentials are explicitly configured; source credentials and principals are not forwarded. Pure local development uses URLs for cross-Worker calls because it has no hosted Project identity.
-
-This requires matching SDK, CLI, server and Worker Runtime support and rebuilding immutable bundles. Task Sessions opt into `durable-object-worker-namespace-v1`; existing ordinary Session storage is unchanged. Channel wakeups, approval relay, active-child steering and execution recovery after a host crash remain deferred.
-
 ### Worker build plugins
 
 The Node-only `@gea-ai/agent-sdk/worker-build-plugins` entry exports the shared
@@ -737,7 +906,7 @@ Applications call `/api/v1` using `fetch`, `curl` or another HTTP client. Payloa
 use JSON and streams use AI SDK UI-message SSE. The Agent SDK owns Agent execution;
 calling the HTTP API does not require an SDK client.
 
-Hosted requests use an Application user OAuth token. An independently running
+Hosted requests use a Project API Key or a Project user OAuth token. An independently running
 `gea agent dev --model-source local --api-port 8788` exposes token-free local access:
 
 ```sh
@@ -759,3 +928,10 @@ read-only through the local API.
 
 See the [HTTP integration guide](https://musegea.com/developers/agent-api) and the
 running server's `/api/v1/openapi.json` for routes and payloads.
+
+API callers use ordinary HTTP. Subagents reuse Agent/Session/Run resources,
+with parent/child coordination owned by logical Runs in the SDK Session inbox.
+Internal Task logic has been removed. Worker fetch bindings and remote references
+use the same API, which invokes each Agent at its versioned custom or standard
+Worker route. See the [HTTP integration guide](https://musegea.com/developers/agent-api)
+for authentication and Session/Run operations.