Build a Groovy Integration

{
  "schemaVersion": 1,
  "displayName": "Your Product Name",
  "description": "One sentence about what your product does",
  "capabilityTags": ["ops", "incidents"],
  "skillInstructions": "Use this integration when the user asks about incidents or on-call.",
  "tools": [
    { /* ...tool definitions... */ }
  ]
}

{{arg_name}}              → Tool argument from inputSchema
{{connection.base_url}}   → Saved connection config field
{{connection.api_token}}  → Saved connection secret (decrypted at runtime)
{{runtime.user_id}}       → Current Groovy user ID
{{runtime.trace_id}}      → Current execution trace ID
{{runtime.session_id}}    → Current orchestrator session
{{runtime.turn_id}}       → Current turn (for billing)
{{runtime.device_id}}     → Paired connector device ID

If the entire value is a single {{...}}, the resolved
type is preserved (object/array stays an object/array).
Inside a larger string, it's stringified.

curl -X POST https://your-groovy-url/api/extensions/runners \
  -H "Content-Type: application/json" \
  -b "your-session-cookie" \
  -d '{
    "agentId": "YOUR_AGENT_ID",
    "name": "production-east",
    "endpoint": "https://runner.internal.acme.com:8443",
    "authToken": "runner-secret-token-here",
    "status": "online"
  }'

# Response: { runner: { id: "RUNNER_ID" } }

curl -X POST https://your-groovy-url/api/extensions/EXT_ID/install \
  -H "Content-Type: application/json" \
  -b "your-session-cookie" \
  -d '{
    "runtimeTargetOverride": "customer_runner",
    "runnerId": "RUNNER_ID"
  }'

curl -X POST https://your-groovy-url/api/extensions \
  -H "Content-Type: application/json" \
  -b "your-session-cookie" \
  -d '{
    "extensionId": "EXISTING_EXT_ID",
    "agentId": "YOUR_AGENT_ID",
    "slug": "acmeops",
    "name": "AcmeOps",
    "manifest": { ... updated manifest ... },
    "activate": true
  }'

# A new version is created.
# If activate: true, it becomes the active version immediately.
# If activate: false, the previous version stays live.
# Existing installations automatically use the active version.

curl https://your-groovy-url/api/orchestrator/agents \
  -b "your-session-cookie"

# Response: [{ "id": "YOUR_AGENT_ID", "name": "...", "type": "..." }, ...]
# Use the id of your main orchestrator agent.

{
  "schemaVersion": 1,
  "displayName": "AcmeOps",
  "description": "Incident management for Acme operations teams",
  "capabilityTags": ["incidents", "ops", "on-call"],
  "skillInstructions": "Use AcmeOps tools when the user asks about incidents, outages, on-call, or operational issues. For severity, map urgency words: 'urgent'/'critical'/'P1' → high, 'important' → medium, default → low.",
  "tools": [
    {
      "slug": "list_incidents",
      "name": "List Incidents",
      "description": "List incidents from AcmeOps, optionally filtered by severity or status",
      "riskLevel": "read",
      "authScope": "end_user",
      "inputSchema": {
        "type": "object",
        "properties": {
          "severity": { "type": "string", "enum": ["low", "medium", "high"] },
          "status": { "type": "string", "enum": ["open", "resolved", "all"] }
        }
      },
      "action": {
        "kind": "http_action",
        "method": "GET",
        "url": "{{connection.base_url}}/api/v2/incidents",
        "headers": { "Authorization": "Bearer {{connection.api_token}}" },
        "query": { "severity": "{{severity}}", "status": "{{status}}" }
      }
    },
    {
      "slug": "create_incident",
      "name": "Create Incident",
      "description": "Create a new incident in AcmeOps",
      "riskLevel": "write",
      "authScope": "end_user",
      "inputSchema": {
        "type": "object",
        "properties": {
          "title": { "type": "string", "description": "Short incident title" },
          "severity": { "type": "string", "enum": ["low", "medium", "high"] },
          "description": { "type": "string", "description": "Detailed description" }
        },
        "required": ["title", "severity"]
      },
      "action": {
        "kind": "http_action",
        "method": "POST",
        "url": "{{connection.base_url}}/api/v2/incidents",
        "headers": {
          "Authorization": "Bearer {{connection.api_token}}",
          "Content-Type": "application/json"
        },
        "body": {
          "title": "{{title}}",
          "severity": "{{severity}}",
          "description": "{{description}}"
        }
      }
    },
    {
      "slug": "close_incident",
      "name": "Close Incident",
      "description": "Resolve and close an incident by its ID",
      "riskLevel": "write",
      "authScope": "end_user",
      "inputSchema": {
        "type": "object",
        "properties": {
          "incident_id": { "type": "string", "description": "Incident ID (e.g. INC-4821)" },
          "resolution": { "type": "string", "description": "Resolution summary" }
        },
        "required": ["incident_id"]
      },
      "action": {
        "kind": "http_action",
        "method": "POST",
        "url": "{{connection.base_url}}/api/v2/incidents/{{incident_id}}/resolve",
        "headers": { "Authorization": "Bearer {{connection.api_token}}" },
        "body": { "resolution": "{{resolution}}" }
      }
    }
  ]
}