Version: 1.1.0  |  Last updated: 19 June 2026  |  Applies to: Agent Registry Container

The Agent Registry is a Docker container that hosts one or more A2A (Agent-to-Agent) agents on a single port and exposes them for registration with the Spotfire Copilot™ orchestrator. In development mode it also enables optional tools (MCP server, WebSocket reverse tunnel, type-stub generator) for building custom agents locally.

This guide covers two audiences:

• Spotfire administrators deploying the Agent Registry to a cloud platform (Azure, GCP, AWS, or Kubernetes) or on-premise so that agents are reachable from a deployed orchestrator.

• Spotfire developers running the Agent Registry locally on their workstation to build, test, and tunnel custom agents into a deployed orchestrator without opening any inbound ports.

The Agent Registry depends on a deployed Spotfire Copilot™ orchestrator. If you have not yet installed the orchestrator, see the Spotfire Copilot™ Installation Guide (Backend) first.

What's New in 1.1

• MCP development server now requires VS Code 1.109 or later. The MCP Apps UI surface (design form, welcome screens, interactive components) was updated for the stable MCP Apps protocol shipped in VS Code 1.109. Earlier VS Code builds will not render the rich UI; upgrade VS Code before running MCP_ENABLED=true. See section 7, Enabling the MCP Development Server.

• Toolkit marking fixes. Reworked the mark_rows_* operations and helpers for reliable round-tripping with Spotfire:

  • mark_rows_ops_from_tuples is now the single supported public API for batched marking and emits one op per batch with a fixed batch size of 100 rows.

  • The lower-level helper is now private; a new MarkingBatchError surfaces partial failures instead of silently dropping rows.

  • Updated scaffolding templates and the viz-data-shaping skill to recommend the new API.

• Agent stability fixes.

  • The registry no longer silently demotes a failing code agent to a no-code stub — failures are reported and the agent is taken out of rotation.

  • Remove → re-add cycles on the in-process file watcher no longer leave stale Starlette mounts or executors behind.

  • A new in-process file watcher hot-reloads custom workflows without dropping the MCP connection.

• Tracing and monitoring improvements.

  • Per-conversation log files now include an executor diagnostic block on every turn, making it easier to correlate orchestrator requests with stage execution.

  • The dry-run harness (dry_run_agent) prepends an unmissable PASS / PASS-PARTIAL / FAIL banner above its JSON report.

• Spotfire marking topology guidance added to the viz-data-shaping and marked-data skills, covering semantic column mapping and viz property paths.

1. Introduction

1.1 What You Are Deploying

The Agent Registry is a single Docker container that serves one or more Spotfire Copilot™ agents over the A2A protocol. A single image plays two roles:

• In production, it hosts a fixed set of bundled agents plus any custom agents mounted at CUSTOM_WORKFLOWS_DIR, behind OAuth2 bearer-token authentication. A deployed orchestrator calls it directly over HTTP after an administrator registers each agent in the orchestrator's admin console.

• In development, the same image runs on a developer's laptop with development features enabled. Hot-reload, type-stub generation, the MCP development server, and a WebSocket reverse tunnel into a deployed orchestrator allow agent code to be written, validated, and tested end-to-end against the orchestrator without opening any inbound ports.

The container provides:

• Multi-agent hosting — each agent is served at /agents/<slug>/ and auto-publishes its agent card at <endpoint>/.well-known/agent-card.json

• OAuth2 client-credentials authentication — a /token endpoint issues short-lived JWTs that protect every agent endpoint

• Auto-discovery — bundled agents and any custom agents mounted at CUSTOM_WORKFLOWS_DIR are discovered at startup and on file change

• Orchestrator relay — outbound LLM calls and RAG retrieval are proxied to the orchestrator using a single configured OAuth2 client, so agents do not hold their own LLM credentials

• WebSocket reverse tunnel (development only) — registers locally-running agents with a deployed orchestrator without inbound ports

• MCP development server (development only) — exposes scaffolding, dry-run, and read-skill tools to AI coding assistants over the Model Context Protocol

• Shared visualization capabilities — well-log, standard, and advanced visualization helpers are available to every agent

The MCP server and tunnel are development-only features. Both are disabled unless you explicitly opt in, and must remain disabled in production deployments. See section 11, Security Best Practices.

1.2 Architecture Overview

The Agent Registry runs as one container from a single Docker image. There is no database to provision and no separate admin console — registration state lives in the orchestrator.

One image, two deployment shapes. The same image binary serves production and development. Production deployments run the image with its default startup command and minimal environment. Local development sets MCP_ENABLED=true and TUNNEL_ENABLED=true and bind-mounts a custom-agents directory; nothing about the image itself changes.

Production (HTTP Direct): The orchestrator makes direct HTTP calls to the Agent Registry. Requires inbound firewall rules to allow the orchestrator to reach the registry's BASE_URL.

Development (WebSocket Tunnel): A local Agent Registry opens an outbound WebSocket to the orchestrator's /tunnel/connect endpoint and registers its agents. The orchestrator proxies requests back over the same tunnel. No inbound ports or firewall changes required — the connection is always initiated by the registry. Tunneled agents are scoped to the developer's Spotfire user ID and appear only in that user's Copilot session.

Both modes use the same OAuth2 client credentials to authenticate the Agent Registry to the orchestrator. The tunnel requires that client to hold the agents:write scope (granted automatically by the agent_developer scope profile — see Orchestrator OAuth2 Client in section 3).

Health Check Endpoints

⚠️ The Agent Registry exposes two distinct health endpoints. Using the wrong one in your platform's probe configuration will cause restart loops.

# Liveness — is the process up?
curl -f http://localhost:8050/healthz

# Readiness — are agents discovered and ready?
curl -f http://localhost:8050/readyz

Platform-specific configuration:

Do not point health probes at / or at any /agents/... path. The root path returns 404; the agent endpoints require a bearer token and will return 401. Either will be treated as a failure and the container will be restarted in a loop.

Pulling the Docker Image

The Agent Registry is distributed exclusively via the Azure Container Registry at copilotoci.azurecr.io. There is no public ECR mirror — credentials are required for every environment that pulls the image.

Obtain registry credentials and pull

1. Request access. Open a case via the Spotfire Support Portal selecting Spotfire Enterprise as the Product and request access to the Spotfire Copilot OCI registry. Support will issue a registry username and password/token. The same credentials grant access to the orchestrator image, the Agent Registry image, and any data-loader images.

2. Log in to the registry on every host that will pull the image (developer workstations, CI runners, and production hosts):

   docker login copilotoci.azurecr.io
   # Helm-based deployments:
   helm registry login copilotoci.azurecr.io
   

3. Pull the image:

   docker pull copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0
   

For login command details, version policy, troubleshooting registry auth errors, and the complete artifact catalog, consult the OCI Registry Access Guide.

Cloud and Kubernetes deployments: create an image-pull secret using your registry credentials and reference it from your deployment manifest. For example, on Kubernetes:

kubectl create secret docker-registry copilotoci-pull \
  --docker-server=copilotoci.azurecr.io \
  --docker-username='<registry-username>' \
  --docker-password='<registry-password-or-token>'

Then add imagePullSecrets: [{ name: copilotoci-pull }] to each deployment that pulls from copilotoci.azurecr.io. AWS ECS, Azure Container Apps, and GCP Cloud Run have equivalent registry-credential mechanisms — see the platform-specific subsections in section 5.

Air-gapped / private registry mirroring

If your deployment environment cannot reach the upstream registry, pull on an internet-connected machine, retag, and push to your internal registry:

docker login copilotoci.azurecr.io
docker pull copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0
docker tag  copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0 \
            your-registry.example.com/agent-container:1.1.0
docker push your-registry.example.com/agent-container:1.1.0

Update all deployment manifests and compose files to reference your internal registry URL.

1.3 Prerequisites

Before you begin, ensure you have:

1.4 Recommended Personnel

For production deployments, an IT / Analytics Engineer familiar with:

• Deploying containerized applications to at least one cloud platform (Azure Container Apps, GCP Cloud Run, AWS ECS/Fargate, or Kubernetes)

• Managing environment variables, secrets, and image-pull credentials via the platform's native secrets store

• Configuring health probes, ingress, and TLS termination

• Working with OAuth2 client credentials and bearer-token authentication

For local agent development, a Spotfire developer familiar with:

• Docker Desktop and Docker Compose

• Python 3.11+ and uv (for the type-stubs virtual environment)

• VS Code and GitHub Copilot (for the MCP development server)

• The conceptual structure of an A2A agent — see Spotfire A2A Agents Guide

2. Choose Your Deployment Path

The Agent Registry supports the same set of deployment targets as the orchestrator, plus a first-class local development path. Identify your scenario first:

Where will you run the Agent Registry?

All paths share Steps 1–2. Credentials and orchestrator wiring work the same way. The differences begin in Step 3, where the deployment mechanism and runtime profile diverge.

3. Step 1 — Generate Credentials

Applies to: All deployments.

The Agent Registry uses two independent sets of OAuth2 client credentials:

1. Local container credentials (AUTH_*) — used by Spotfire clients and the orchestrator to authenticate against the Agent Registry's own /token endpoint when calling its agents.

2. Orchestrator OAuth2 client (ORCHESTRATOR_*) — used by the Agent Registry to authenticate outbound calls to the orchestrator (LLM relay, RAG, agent registration, and the tunnel).

Generate both before deploying.

Local Container Credentials

The Agent Registry itself does not ship a credential generator — the same generate_credentials.py helper that produces orchestrator credentials, distributed with Spotfire Copilot™, also produces all three values needed here. Run it once and copy the outputs into your Agent Registry environment:

# Run the helper from your Spotfire Copilot install
python generate_credentials.py

This outputs three values for the Agent Registry:

1. AUTH_CLIENT_ID — a short, opaque client identifier

2. AUTH_CLIENT_SECRET — a randomly generated secret (shown only once)

3. AUTH_SIGNING_KEY — a URL-safe random key used to sign issued JWTs

Save the plaintext secret immediately — AUTH_CLIENT_SECRET is shown only once. For on-premise and local development, paste it into your .env file. For cloud deployments, store it in your platform's secrets manager (Azure Key Vault, GCP Secret Manager, AWS Secrets Manager, or Kubernetes Secrets) and reference it from your deployment manifest.

If you do not have access to the helper, generate the three values manually with any Python 3.11+ interpreter:

# AUTH_CLIENT_ID — any short identifierecho "agent-registry-$(date +%s)"

# AUTH_CLIENT_SECRET — a 32-byte URL-safe random string
python -c "import secrets; print(secrets.token_urlsafe(32))"

# AUTH_SIGNING_KEY — a separate 32-byte URL-safe random string
python -c "import secrets; print(secrets.token_urlsafe(32))"

Orchestrator OAuth2 Client

Register an OAuth2 client in the orchestrator using the agent_developer scope profile. This profile grants exactly the scopes the Agent Registry needs and nothing more:

Option A — Admin Console (recommended)

1. Open the orchestrator's admin console (e.g., http://localhost:8080/admin).

2. Navigate to the OAuth Clients tab.

3. Click Create Client and fill in:

   • Client Name: a descriptive label such as agent-registry-prod or agent-registry-dev-<your-name>

   • Scope Profile: agent_developer

4. Click Create. The console displays the generated client_id and client_secret.

The client_secret is shown only once. Copy both values immediately. Use them as ORCHESTRATOR_CLIENT_ID and ORCHESTRATOR_CLIENT_SECRET.

Option B — REST API

curl -X POST https://your-orchestrator.example.com/register_client \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_name=Agent Registry&scope_profile=agent_developer"

Response:

{"client_id": "abc123...","client_secret": "s3cr3t..."}

If you must pass scopes explicitly (no profile), use: scopes=api_access rag agents agents:write store (space-separated).

4. Step 2 — Configure the Orchestrator Connection

Pick one of two connection modes based on where the Agent Registry will run.

HTTP Direct (Production)

The orchestrator opens HTTP connections to the Agent Registry on its configured BASE_URL. This is the mode used by every cloud and on-premise production deployment.

# .env  (or your platform's secret store)
ORCHESTRATOR_URL=https://orchestrator.example.com
ORCHESTRATOR_CLIENT_ID=<from Step 1 — Orchestrator OAuth2 Client>
ORCHESTRATOR_CLIENT_SECRET=<from Step 1>

BASE_URL=https://agents.example.com   # how the orchestrator reaches *this* container
TUNNEL_ENABLED=false                  # explicitly disabled in production

Once the container is running, an administrator registers each agent in the orchestrator admin console at the URL ${BASE_URL}/agents/<slug>/ — see section 6, Step 4 — Verify and Register Agents.

WebSocket Tunnel (Local Development)

The Agent Registry opens an outbound WebSocket to the orchestrator's /tunnel/connect endpoint, authenticates using the same ORCHESTRATOR_* credentials, and registers each discovered agent as a tunneled agent scoped to a specific Spotfire user. Inbound A2A requests are proxied back over the tunnel.

# .env  (developer workstation)
ORCHESTRATOR_URL=https://orchestrator.example.com
ORCHESTRATOR_CLIENT_ID=<from Step 1 — Orchestrator OAuth2 Client>
ORCHESTRATOR_CLIENT_SECRET=<from Step 1>

TUNNEL_ENABLED=true
TUNNEL_USER_ID=alice.smith@company.com   # MUST exactly match your Spotfire login
MCP_ENABLED=true                         # enable the MCP development server

⚠️ TUNNEL_USER_ID must exactly match the username of your active Spotfire session. The orchestrator routes inbound A2A requests to a tunnel based on this value: if Spotfire is logged in as alice.smith@company.com and the tunnel announces itself as Alice.Smith@COMPANY.COM, the tunneled agents will not appear in that Spotfire session. The match is case-sensitive and includes any domain/realm portion. If your tunneled agents are not visible in Spotfire Copilot, this is almost always the cause.

Requirements:

• The orchestrator must have the /tunnel/connect endpoint enabled (TUNNEL_ENABLED=true on the orchestrator side — see the Spotfire Copilot™ Installation Guide for the corresponding orchestrator-side variables).

• The ORCHESTRATOR_CLIENT_* credentials must hold the agents:write scope. The agent_developer profile grants this automatically.

• Tunneled agents are visible only to the Spotfire user whose login matches TUNNEL_USER_ID. Other users on the same orchestrator will not see them, even when the tunnel is live.

Production deployments must set TUNNEL_ENABLED=false (or omit the variable). The cloud and on-premise deployment examples in §5 do not set it, so it is off by default in production.

5. Step 3 — Deploy

Image references below pin version 1.1.0. All snippets pull from copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0. You must already have logged in to that registry with credentials issued by Spotfire Support — see Pulling the Docker Image in section 1 and the OCI Registry Access Guide.

Key pattern for all platforms: You deploy the same Docker image in every environment. The differences are the environment variables (MCP_ENABLED/TUNNEL_ENABLED for development), the volumes (mounting your custom-agents directory at CUSTOM_WORKFLOWS_DIR), and how you supply secrets.

Managing Environment Variables in the Cloud

In cloud deployments, you do not use .env files. Each cloud platform has its own mechanism for injecting environment variables and secrets into containers:

Best practices

• Never embed secrets in container images or source control. Use your platform's secrets manager.

• Separate secrets from configuration. Use a Secret (or Key Vault / Secrets Manager) for AUTH_CLIENT_SECRET, AUTH_SIGNING_KEY, and ORCHESTRATOR_CLIENT_SECRET. Use plain environment variables for non-sensitive settings like LOG_LEVEL, BASE_URL, and ORCHESTRATOR_URL.

• BASE_URL must match how the orchestrator reaches the registry. Behind a reverse proxy or ingress, set this to the externally-visible URL (e.g., https://agents.example.com). It is used to build the URLs published in each agent's card.

• Bcrypt-style $ characters do not appear in Agent Registry credentials. Unlike the orchestrator's HASHED_ADMIN_PASSWORD, none of the Agent Registry's required values contain $ interpolation hazards. Standard secret storage is sufficient on every platform.

Required environment variables (all platforms)

5.1 Local Development (Docker Desktop)

Use this option for building, testing, and tunneling custom agents into a deployed orchestrator. Both the bundled agents and any agents in your workspace are served, with hot-reload on every save.

Prerequisites: Docker Desktop on Windows or macOS (or Docker Engine + Compose V2 on Linux), authenticated access to copilotoci.azurecr.io, and a deployed orchestrator you can reach.

Prepare the workspace

1. Choose a directory on your host for custom agents — this is where you will create and edit agent code:

   C:\Users\you\my_agents\
     ├── .vscode\
     │   └── mcp.json
     ├── docker-compose.yml      # created in step 2
     ├── .env                    # created in step 3
     └── (agent folders appear here as you create them)
   

2. Save the following docker-compose.yml next to your .env. It pulls the image directly — no source checkout required.

   services:agent-registry:
       image: copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0
       ports:
         - "8050:8050"
       env_file: .env
       volumes:
         # Mount your custom-agents directory into the container
         - .:/custom-workflows
       restart: unless-stopped

3. Create a .env file next to the compose file with the values from Steps 1 and 2:

   # Reach a locally-running orchestrator from inside the container
   ORCHESTRATOR_URL=http://host.docker.internal:8080
   ORCHESTRATOR_CLIENT_ID=<from Step 1>
   ORCHESTRATOR_CLIENT_SECRET=<from Step 1>
   
   AUTH_CLIENT_ID=<from Step 1>
   AUTH_CLIENT_SECRET=<from Step 1>
   AUTH_SIGNING_KEY=<from Step 1>
   
   # Custom-agents directory inside the container (matches the volume mount above)
   CUSTOM_WORKFLOWS_DIR=/custom-workflows
   
   # Development features
   MCP_ENABLED=true
   TUNNEL_ENABLED=true
   TUNNEL_USER_ID=alice.smith@company.com   # MUST exactly match your Spotfire login

   \u26a0\ufe0f TUNNEL_USER_ID is how Spotfire Copilot routes tunneled agents to your session. It must match the username of the Spotfire user you are logged in as, exactly — including case, domain, and any realm portion. Set it wrong and your agents will not appear in Spotfire even though the tunnel is live.

Start the container

docker compose up -d

When the container starts it will:

• Discover every agent under your custom-agents directory and serve it at /agents/<slug>/

• Open an outbound WebSocket to the orchestrator and register each agent scoped to TUNNEL_USER_ID

• Watch the custom-agents directory for changes and re-expose edited agents in-process without a restart

• Expose the MCP development server at http://localhost:8050/mcp/ for use from VS Code

Verify and use

# Liveness
curl http://localhost:8050/healthz

# Readiness (after the tunnel has connected)
curl http://localhost:8050/readyz

Open Spotfire Copilot in your browser — your tunneled agents appear under your user account, provided TUNNEL_USER_ID matches your Spotfire login.

For the workspace layout, type stubs, and MCP server setup, see section 7, Step 5 — Set Up the Local Agent Workspace.

5.2 Azure Container Apps

Prerequisites: Azure subscription, az CLI installed and authenticated, an Azure Container Apps Environment, and an OCI image-pull credential or registry secret for copilotoci.azurecr.io.

Provision the environment

az group create --name SpotfireAgents --location eastus

az containerapp env create \
  --name agents-env \
  --resource-group SpotfireAgents \
  --location eastus

Store secrets in Azure Key Vault

az keyvault create --name spotfire-agents-kv \
  --resource-group SpotfireAgents --location eastus

az keyvault secret set --vault-name spotfire-agents-kv --name auth-client-secret    --value "<AUTH_CLIENT_SECRET>"
az keyvault secret set --vault-name spotfire-agents-kv --name auth-signing-key      --value "<AUTH_SIGNING_KEY>"
az keyvault secret set --vault-name spotfire-agents-kv --name orchestrator-secret   --value "<ORCHESTRATOR_CLIENT_SECRET>"

Configure the image-pull credential

az containerapp env identity assign \
  --name agents-env --resource-group SpotfireAgents --system-assigned

# OR, attach OCI registry credentials directly on the container app:
az containerapp registry set \
  --name agent-registry \
  --resource-group SpotfireAgents \
  --server copilotoci.azurecr.io \
  --username '<registry-username>' \
  --password '<registry-password-or-token>'

Deploy the Agent Registry

az containerapp create \
  --name agent-registry \
  --resource-group SpotfireAgents \
  --environment agents-env \
  --image copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0 \
  --target-port 8050 \
  --ingress external \
  --min-replicas 1 \
  --secrets \
    auth-client-secret=keyvaultref:https://spotfire-agents-kv.vault.azure.net/secrets/auth-client-secret,identityref:/subscriptions/.../managedIdentities/agents-id \
    auth-signing-key=keyvaultref:https://spotfire-agents-kv.vault.azure.net/secrets/auth-signing-key,identityref:... \
    orchestrator-secret=keyvaultref:https://spotfire-agents-kv.vault.azure.net/secrets/orchestrator-secret,identityref:... \
  --env-vars \
    AUTH_CLIENT_ID=<AUTH_CLIENT_ID> \
    AUTH_CLIENT_SECRET=secretref:auth-client-secret \
    AUTH_SIGNING_KEY=secretref:auth-signing-key \
    ORCHESTRATOR_URL=https://orchestrator.example.com \
    ORCHESTRATOR_CLIENT_ID=<ORCHESTRATOR_CLIENT_ID> \
    ORCHESTRATOR_CLIENT_SECRET=secretref:orchestrator-secret \
    BASE_URL=https://agent-registry.<random>.eastus.azurecontainerapps.io \
    LOG_LEVEL=INFO

BASE_URL chicken-and-egg. The externally-visible URL is allocated by Azure when the Container App is created. Deploy first with a placeholder, capture the FQDN with az containerapp show ... --query properties.configuration.ingress.fqdn, then update BASE_URL to https://<that-fqdn> and revise the app.

Health probe path: /healthz on port 8050.

5.3 GCP Cloud Run

Prerequisites: GCP project, gcloud CLI installed and authenticated, and GCP Secret Manager enabled.

Store secrets in GCP Secret Manager

echo -n "<AUTH_CLIENT_SECRET>"        | gcloud secrets create agent-auth-client-secret  --data-file=-
echo -n "<AUTH_SIGNING_KEY>"          | gcloud secrets create agent-auth-signing-key    --data-file=-
echo -n "<ORCHESTRATOR_CLIENT_SECRET>"| gcloud secrets create agent-orchestrator-secret --data-file=-

# Grant the Cloud Run service account accessfor s in agent-auth-client-secret agent-auth-signing-key agent-orchestrator-secret ; do
  gcloud secrets add-iam-policy-binding "$s" \
    --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"done

Configure the image-pull credential

Cloud Run can pull from Azure Container Registry using a service-account-mounted Docker config, or via Workload Identity Federation. The simplest approach is a per-region Artifact Registry mirror — pull the image once with your OCI credentials, push to Artifact Registry, and reference that copy.

Deploy

gcloud run deploy agent-registry \
  --image copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0 \
  --port 8050 \
  --region us-central1 \
  --min-instances 1 \
  --set-env-vars \
    AUTH_CLIENT_ID=<AUTH_CLIENT_ID>,\
    ORCHESTRATOR_URL=https://orchestrator.example.com,\
    ORCHESTRATOR_CLIENT_ID=<ORCHESTRATOR_CLIENT_ID>,\
    LOG_LEVEL=INFO \
  --set-secrets \
    AUTH_CLIENT_SECRET=agent-auth-client-secret:latest,\
    AUTH_SIGNING_KEY=agent-auth-signing-key:latest,\
    ORCHESTRATOR_CLIENT_SECRET=agent-orchestrator-secret:latest

# After deploy, capture the URL and update BASE_URL
URL=$(gcloud run services describe agent-registry --region us-central1 --format='value(status.url)')
gcloud run services update agent-registry --region us-central1 \
  --update-env-vars BASE_URL=$URL

Startup probe path: /readyz on port 8050. Liveness probe path: /healthz on port 8050.

5.4 AWS (ECS / Fargate)

Prerequisites: AWS account, aws CLI installed and authenticated, an ECS cluster, AWS Secrets Manager enabled, and an ECR mirror (or AWS-managed pull secret) for the OCI image.

Store secrets

aws secretsmanager create-secret --name agent-registry/auth-client-secret  --secret-string "<AUTH_CLIENT_SECRET>"
aws secretsmanager create-secret --name agent-registry/auth-signing-key    --secret-string "<AUTH_SIGNING_KEY>"
aws secretsmanager create-secret --name agent-registry/orchestrator-secret --secret-string "<ORCHESTRATOR_CLIENT_SECRET>"

Task role

The Agent Registry itself does not require AWS service permissions. The task role only needs to read its secrets:

{"Version": "2012-10-17","Statement": [
    {
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": "arn:aws:secretsmanager:*:*:secret:agent-registry/*"
    }]}

Task definition

{"family": "agent-registry","networkMode": "awsvpc","requiresCompatibilities": ["FARGATE"],"cpu": "1024","memory": "2048","taskRoleArn": "arn:aws:iam::...:role/agent-registry-task","executionRoleArn": "arn:aws:iam::...:role/ecsTaskExecutionRole","containerDefinitions": [
    {
      "name": "agent-registry",
      "image": "copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0",
      "portMappings": [{ "containerPort": 8050 }],
      "environment": [
        { "name": "AUTH_CLIENT_ID",         "value": "<AUTH_CLIENT_ID>" },
        { "name": "ORCHESTRATOR_URL",       "value": "https://orchestrator.example.com" },
        { "name": "ORCHESTRATOR_CLIENT_ID", "value": "<ORCHESTRATOR_CLIENT_ID>" },
        { "name": "BASE_URL",               "value": "https://agents.example.com" },
        { "name": "LOG_LEVEL",              "value": "INFO" }
      ],
      "secrets": [
        { "name": "AUTH_CLIENT_SECRET",         "valueFrom": "arn:aws:secretsmanager:...:secret:agent-registry/auth-client-secret" },
        { "name": "AUTH_SIGNING_KEY",           "valueFrom": "arn:aws:secretsmanager:...:secret:agent-registry/auth-signing-key" },
        { "name": "ORCHESTRATOR_CLIENT_SECRET", "valueFrom": "arn:aws:secretsmanager:...:secret:agent-registry/orchestrator-secret" }
      ],
      "healthCheck": {
        "command": ["CMD-SHELL", "curl -f http://localhost:8050/healthz || exit 1"],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 30
      }
    }]}

5.5 Kubernetes

Applies to: AKS (Azure), GKE (Google), EKS (Amazon), or any conformant Kubernetes cluster (v1.25+).

Image-pull secret

kubectl create namespace spotfire-agents

kubectl -n spotfire-agents create secret docker-registry copilotoci-pull \
  --docker-server=copilotoci.azurecr.io \
  --docker-username='<registry-username>' \
  --docker-password='<registry-password-or-token>'

Application secrets and config

apiVersion: v1kind: Secretmetadata:name: agent-registry-secretsnamespace: spotfire-agentstype: OpaquestringData:AUTH_CLIENT_SECRET: "<AUTH_CLIENT_SECRET>"AUTH_SIGNING_KEY: "<AUTH_SIGNING_KEY>"ORCHESTRATOR_CLIENT_SECRET: "<ORCHESTRATOR_CLIENT_SECRET>"---apiVersion: v1kind: ConfigMapmetadata:name: agent-registry-confignamespace: spotfire-agentsdata:AUTH_CLIENT_ID: "<AUTH_CLIENT_ID>"ORCHESTRATOR_URL: "https://orchestrator.example.com"ORCHESTRATOR_CLIENT_ID: "<ORCHESTRATOR_CLIENT_ID>"BASE_URL: "https://agents.example.com"LOG_LEVEL: "INFO"

Deployment

apiVersion: apps/v1kind: Deploymentmetadata:name: agent-registrynamespace: spotfire-agentsspec:replicas: 2selector:
    matchLabels:
      app: agent-registrytemplate:
    metadata:
      labels:
        app: agent-registry
    spec:
      imagePullSecrets:
        - name: copilotoci-pull
      containers:
        - name: agent-registry
          image: copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0
          ports:
            - containerPort: 8050
          envFrom:
            - configMapRef:
                name: agent-registry-config
            - secretRef:
                name: agent-registry-secrets
          livenessProbe:
            httpGet: { path: /healthz, port: 8050 }
            initialDelaySeconds: 15
            periodSeconds: 10
          readinessProbe:
            httpGet: { path: /readyz, port: 8050 }
            initialDelaySeconds: 10
            periodSeconds: 5
          resources:
            requests:
              cpu: 250m
              memory: 512Mi
            limits:
              cpu: "1"
              memory: 1Gi

Service and Ingress

apiVersion: v1kind: Servicemetadata:name: agent-registrynamespace: spotfire-agentsspec:selector:
    app: agent-registryports:
    - port: 8050
      targetPort: 8050---apiVersion: networking.k8s.io/v1kind: Ingressmetadata:name: agent-registrynamespace: spotfire-agentsspec:tls:
    - hosts: [agents.example.com]
      secretName: agent-registry-tlsrules:
    - host: agents.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: agent-registry
                port:
                  number: 8050

Mounting custom agents

To serve custom agents in a Kubernetes deployment, mount them at CUSTOM_WORKFLOWS_DIR from a ConfigMap, a PersistentVolumeClaim backed by your cloud's file storage (Azure Files, GCP Filestore, AWS EFS), or a sidecar that syncs from Git:

spec:template:
    spec:
      containers:
        - name: agent-registry
          env:
            - name: CUSTOM_WORKFLOWS_DIR
              value: /custom-workflows
          volumeMounts:
            - name: custom-agents
              mountPath: /custom-workflows
              readOnly: true
      volumes:
        - name: custom-agents
          persistentVolumeClaim:
            claimName: custom-agents-pvc

5.6 On-Premise (Docker Compose)

Use this option for production deployments on a single host, or for proof-of-concept work in environments without cloud infrastructure.

Prerequisites: Docker Engine 20.10+ with Docker Compose V2. Outbound HTTPS to copilotoci.azurecr.io (or access to your air-gapped mirror).

Create a deployment directory

Pick any directory on the host \u2014 for example /opt/spotfire-agent-registry/ \u2014 and create the following two files in it:

docker-compose.yml

services:agent-registry:
    image: copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0
    ports:
      - "${PORT:-8050}:8050"
    env_file: .env
    volumes:
      # Optional: mount a host directory containing additional agents.
      # Mount read-only \u2014 the container never needs to write to it.
      - /opt/spotfire-agents:/custom-workflows:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8050/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

.env \u2014 fill in with values from Steps 1 and 2:

# Local container credentials (from Step 1)
AUTH_CLIENT_ID=<from Step 1>
AUTH_CLIENT_SECRET=<from Step 1>
AUTH_SIGNING_KEY=<from Step 1>

# Orchestrator relay credentials (from Step 1)
ORCHESTRATOR_URL=https://orchestrator.example.com
ORCHESTRATOR_CLIENT_ID=<from Step 1>
ORCHESTRATOR_CLIENT_SECRET=<from Step 1>

# Public URL the orchestrator uses to reach this host
BASE_URL=https://agents.example.com

# Custom-agents directory inside the container (matches the volume mount above)
CUSTOM_WORKFLOWS_DIR=/custom-workflows

Remove the volumes: block entirely if you do not need to mount custom agents \u2014 the container ships with a set of bundled agents and will run without any mount.

Start, inspect, and stop

# Start
docker compose up -d

# Tail logs
docker compose logs -f agent-registry

# Stop
docker compose down

# Update to a newer image
docker compose pull && docker compose up -d

6. Step 4 — Verify and Register Agents

Health checks

# On-premise / local
curl http://localhost:8050/healthz
curl http://localhost:8050/readyz

# Cloud
curl https://agents.example.com/healthz
curl https://agents.example.com/readyz

Both should return 200 OK with {"status":"ok"}.

Confirm agent cards are published

Every discovered agent exposes its card at ${BASE_URL}/agents/<slug>/.well-known/agent-card.json. The slug is the folder name with underscores replaced by hyphens.

# Bundled mock agent — always present
curl https://agents.example.com/agents/mock-multiturn/.well-known/agent-card.json

# Your custom agent
curl https://agents.example.com/agents/turbine-analyst/.well-known/agent-card.json

If the response is a JSON document describing the agent's name, description, and skills, the agent is discoverable.

Register an agent in the orchestrator

Only required for HTTP-direct deployments. Tunneled agents (development mode) register themselves automatically when the tunnel connects.

In the orchestrator admin console (https://orchestrator.example.com/admin):

1. Navigate to the Agents tab.

2. Click Register Agent and provide:

   • Endpoint URL: ${BASE_URL}/agents/<slug>/ — the trailing slash matters.

   • Authentication: OAuth2 client credentials

   • Token URL: ${BASE_URL}/token

   • Client ID / Client Secret: the AUTH_CLIENT_ID and AUTH_CLIENT_SECRET from section 3, Step 1 — Generate Credentials

3. Click Test Connection — the console will fetch the agent card and confirm authentication works.

4. Save to make the agent visible to Spotfire users.

Repeat for each agent you want exposed. The orchestrator's admin console caches the agent card; if you change an agent's metadata, re-test or restart registration to refresh the cache.

7. Step 5 — Set Up the Local Agent Workspace (Developers)

Applies to: Local development workstations running the container with MCP_ENABLED=true and TUNNEL_ENABLED=true (see section 5.1, Local Development). Skip this section for production deployments.

Workspace Layout

Create a directory anywhere on your host for custom agents. The Agent Registry mounts this directory at /custom-workflows and auto-discovers anything inside it:

my_agents/
├── .vscode/
│   └── mcp.json                                    # MCP server config for VS Code
├── docker-compose.yml                              # from §5.1
├── .env                                            # from §5.1
├── agent_registry_toolkit_for_spotfire_stubs-*.whl # Type stubs (copied in by the `setup_workspace` MCP tool)
└── turbine_analyst/                                # Your first agent
    ├── description.txt                             # No-code agent root file
    ├── SPEC.md                                     # Design spec (written by confirm_design)
    ├── TDD.md                                      # Technical design (written by confirm_technical_design)
    ├── prompts/
    │   ├── base/
    │   │   ├── system/
    │   │   │   ├── role_intro.txt
    │   │   │   ├── intent_classification.txt
    │   │   │   ├── output_rules.txt
    │   │   │   └── data_schema.txt
    │   │   ├── config/
    │   │   │   ├── messages.json
    │   │   │   ├── column_patterns.json
    │   │   │   └── orchestrator_params.json
    │   │   └── ui/
    │   │       ├── welcome.txt
    │   │       └── metadata_hint.txt
    │   └── intents/
    │       └── analyze_data.txt
    └── stages/                                     # Code agents only
        └── <intent_name>.py

The docker-compose.yml from section 5.1 mounts the directory containing the compose file at /custom-workflows, so the workspace and the mount line up automatically. There is nothing to point at — drop new agent folders next to your .env and they appear at /agents/<slug>/.

Type Stubs for IDE Autocomplete

Code-based agents import from agent_registry_toolkit_for_spotfire, which is installed inside the container at runtime. To get IDE autocomplete, type checking, and inline documentation on your host, install the type-stubs wheel into a local virtual environment.

1. Get the wheel into your workspace

The wheel is shipped inside the container image. To copy it into your workspace, start the container with MCP_ENABLED=true, open your workspace in VS Code, and ask Copilot Chat (Agent mode):

run setup_workspace

The setup_workspace MCP tool copies the prebuilt agent_registry_toolkit_for_spotfire_stubs-*.whl from inside the container into the root of your custom-agents directory, alongside a pyproject.toml and a .vscode/mcp.json if either is missing. It is safe to re-run — existing files are left untouched.

The setup_workspace tool is part of the MCP development server. It is only available when MCP_ENABLED=true. Production deployments do not expose it.

2. Install the wheel into a local virtual environment

cd my_agents
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linuxsource .venv/bin/activate

pip install agent_registry_toolkit_for_spotfire_stubs-*.whl

After installation, your IDE resolves from agent_registry_toolkit_for_spotfire import ... with full type information. The stubs cover every public module: ops, session, schema_discovery, schema_pipeline, llm, sql_helpers, workflow_loop, filter_state, intent_router, response_parser, stage_executor, and validation.

When you upgrade to a newer container image, re-run setup_workspace and pip install --force-reinstall to refresh the stubs against the new toolkit version.

Enabling the MCP Development Server

The MCP server is mounted at http://localhost:8050/mcp/ when MCP_ENABLED=true. It is exempt from bearer-token authentication for ease of use during development.

VS Code 1.109 or later is required. The MCP Apps UI surface (design form, welcome screens, interactive components rendered in Copilot Chat) targets the stable MCP Apps protocol shipped in VS Code 1.109. On earlier builds, MCP tools that return component blocks degrade to plain JSON and the design form will not render. Confirm your VS Code version via Help → About before opening an issue.

⚠️ The MCP server exposes unauthenticated endpoints that can create files, list agent internals, and read templates. It must be disabled in production. The production deployment examples in sections 5.2 – 5.6 leave MCP_ENABLED unset, so it is off by default in production.

Configure VS Code

Create my_agents/.vscode/mcp.json:

{"servers": {
    "spotfire-agent-dev": {
      "type": "http",
      "url": "http://localhost:8050/mcp/"
    }}}

1. Make sure the container is running with MCP_ENABLED=true.

2. Open the my_agents folder in VS Code.

3. VS Code / GitHub Copilot will auto-discover the MCP server.

4. In Copilot Chat (Agent mode), ask list agents — Copilot invokes the list_agents MCP tool and returns the discovered agents.

For the full development workflow (Design → TDD → Scaffold → Dry-run), see Agent Registry Toolkit User Guide.

Hot-Reload Behaviour

The container watches the mounted custom-agents directory for changes:

Logs are visible on the host. Conversation logs are written to <your custom-agents directory>/logs/<slug>/ automatically, so they appear directly in your workspace without needing docker exec. See the per-agent log files for full Python tracebacks if an agent crashes.

8. Authentication Reference

The Agent Registry uses OAuth2 client credentials end-to-end. Two flows are in play:

Flow 1 — Spotfire / orchestrator → Agent Registry

A caller (the orchestrator, or a test script) obtains a JWT from the Agent Registry's /token endpoint and uses it as a bearer token on every request to /agents/<slug>/.

# Step 1 — Get a token
TOKEN=$(curl -s -X POST http://localhost:8050/token \
  -d "grant_type=client_credentials&client_id=${AUTH_CLIENT_ID}&client_secret=${AUTH_CLIENT_SECRET}" \
  | python -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

# Step 2 — Call an agent
curl -X POST http://localhost:8050/agents/mock-multiturn \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "hello"}],
        "messageId": "msg-1"
      }
    }
  }'

Tokens are signed with AUTH_SIGNING_KEY and expire after AUTH_TOKEN_TTL seconds (default 3600).

Flow 2 — Agent Registry → Orchestrator

The Agent Registry uses ORCHESTRATOR_CLIENT_ID / ORCHESTRATOR_CLIENT_SECRET to obtain an orchestrator token whenever it needs to:

• Relay an LLM call (every prompt-relay agent and every code agent using create_llm_caller)

• Query the orchestrator's vector store (RAG)

• Register or update an agent (used by the tunnel)

• Open the /tunnel/connect WebSocket

Tokens are cached in-process and refreshed automatically as they near expiry.

9. Environment Variable Reference

Required variables (container will not start or operate without these)

Server variables

Custom agent variables

Development variables

Tunnel variables

10. Troubleshooting

Authentication errors

Container startup issues

Local development issues

Orchestrator connectivity

Useful diagnostic commands

# ── On-premise / local Docker Compose ────────────────────────────
docker compose ps
docker compose logs -f dev    # or 'prod'

# ── Inside the container ─────────────────────────────────────────
docker compose exec dev curl -s http://localhost:8050/healthz
docker compose exec dev curl -s http://localhost:8050/readyz

# ── Kubernetes ───────────────────────────────────────────────────
kubectl -n spotfire-agents get pods
kubectl -n spotfire-agents logs deployment/agent-registry --tail=100

# ── Cloud (any platform) ─────────────────────────────────────────
curl -s https://agents.example.com/healthz | python -m json.tool
curl -s https://agents.example.com/readyz  | python -m json.tool

11. Security Best Practices

Disable development features in production

• MCP_ENABLED must be unset or false. The MCP server exposes unauthenticated endpoints that can scaffold files, read templates, and inspect agent internals. The production deployment examples in sections 5.2 – 5.6 leave it unset.

• TUNNEL_ENABLED must be unset or false. The tunnel registers agents under a developer's user ID; that flow is only meaningful on a developer workstation.

• DEBUGPY must be unset. Exposing port 5678 in production allows arbitrary remote code execution via the Python debugger protocol.

Credential management

• Never embed AUTH_CLIENT_SECRET, AUTH_SIGNING_KEY, or ORCHESTRATOR_CLIENT_SECRET in container images or source control. Use your cloud platform's secrets manager (Azure Key Vault, GCP Secret Manager, AWS Secrets Manager) or Kubernetes Secrets.

• Rotate AUTH_SIGNING_KEY periodically. Rotation invalidates all outstanding tokens — schedule it during a maintenance window. Update the secret in your secrets store and restart the container.

• Scope the orchestrator client to agent_developer. Do not grant additional scopes "just in case" — the Agent Registry does not need them.

Network security

• Always terminate TLS in front of the Agent Registry in production. Cloud platforms (Container Apps, Cloud Run, ALB on ECS) terminate TLS at the ingress layer; on-premise, place a reverse proxy (nginx, Traefik, Caddy) in front of port 8050.

• Mount custom-agent volumes read-only in production. Use :ro on Docker Compose volume specs and readOnly: true in Kubernetes volumeMounts. The container never writes to CUSTOM_WORKFLOWS_DIR in normal operation.

• Restrict outbound network egress to the orchestrator's URL and the OCI registry. The Agent Registry has no other outbound dependencies in production.

Container security

• Always pull pinned versions. Reference copilotoci.azurecr.io/spotfirecopilot/agent-container:1.1.0, not :latest. Pinned tags make rollback deterministic.

• Run as non-root. The base image already runs as a non-root user — do not override the user in your manifests.

• Set memory and CPU limits. A runaway agent should be capped rather than allowed to consume the host. The Kubernetes example in §5.5 includes sensible defaults.

Audit and monitoring

• Stream logs to your platform's logging backend (Azure Monitor, GCP Cloud Logging, CloudWatch). The container writes to stdout in JSON-line format and respects LOG_LEVEL.

• Conversation logs land on disk under $CUSTOM_WORKFLOWS_DIR/logs/<slug>/. Ensure your log volume has sufficient capacity and rotation in production deployments that retain logs.

• Review orchestrator OAuth2 client activity in the orchestrator's admin console — the Security Audit tab shows token issuance, failed authentications, and agent-registration events.

Copyright © 2006 – 2026 Cloud Software Group, Inc. All rights reserved.