> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed agents and Signal via GraphQL

> Automate Arize managed agent sandboxes, automations, and Signal issue detection with the GraphQL API: create configs, run jobs, and resolve Signal issues.

Arize AX [managed agents](/docs/ax/agents/build-your-own-agent) run a harness (Claude Code, Codex, Cursor, or OpenCode) inside a sandbox to investigate traces, fix bugs, and open pull requests, either as a one-off session or on a recurring **automation**. [Signal](/docs/ax/observe/signal) is a managed agent that reviews a tracing project on a schedule, groups recurring trace failures into ranked **issues**, and can open a PR or GitHub issue for one. The mutations below provision the sandbox infrastructure (integrations, configs, templates), run and message jobs, manage automations, and drive Signal end to end.

## Find the IDs you need

Most mutations here take a `spaceId`, a `modelId` (project), an `accountId`, or a `sandboxConfigId`/`sandboxIntegrationId`. Start from `viewer` for spaces and projects, and from `account` for account-scoped sandbox resources:

<CodeGroup>
  ```graphql Query theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  query FindManagedAgentIds {
    viewer {
      spaces(first: 20) {
        edges {
          node {
            id
            name
            models(first: 50) {
              edges {
                node { id name }
              }
            }
          }
        }
      }
    }
    account {
      id
      sandboxConfigs { id name isBuiltin }
      sandboxIntegrations { id name provider }
    }
  }
  ```
</CodeGroup>

`sandboxConfigs` and `sandboxIntegrations` are account-scoped, so this returns every config and credential the account has, not just the current space's. See [Using global node IDs](/docs/ax/graphql-reference/overview/how-to-use-graphql/using-global-node-ids) for resolving a GID you already have (for example from a URL) with `node`.

## List sandbox jobs and automations in a space

Once you have a space GID, list its recent sandbox jobs and configured automations in one call:

<CodeGroup>
  ```graphql Query theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  query SandboxJobsAndAutomations($spaceId: ID!) {
    node(id: $spaceId) {
      ... on Space {
        sandboxJobs(first: 20, excludeHarnessEvaluation: true) {
          edges {
            node { id name harness repo isIdle automationId createdAt }
          }
        }
        automations { id name triggerSummary harness lastFiredUnix }
      }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "spaceId": "<SPACE_ID>" }
  ```
</CodeGroup>

`automationId` on a job is null for manual jobs and Setup Repo sessions, so filter on it to separate ad-hoc runs from automation-spawned ones. Reference: [`sandboxJobs` and `automations` on `Space`](/docs/ax/graphql-reference/queries/object-graph#space).

## Create a sandbox integration and attach it to a config

A **sandbox integration** stores the credential (for example a GitHub token) a sandbox injects as an environment variable. A **sandbox config** bundles a repo, a harness, and a set of integrations into a reusable preset:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation CreateIntegration($input: CreateSandboxIntegrationInput!) {
    createSandboxIntegration(input: $input) {
      sandboxIntegration { id name provider }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "accountId": "<ACCOUNT_ID>", "provider": "github", "name": "github-ci-bot",
      "env": [{ "envVar": "GITHUB_TOKEN", "value": "<GITHUB_PAT>" }]
    }
  }
  ```
</CodeGroup>

Then create a config that links it:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation CreateConfig($input: CreateSandboxConfigInput!) {
    createSandboxConfig(input: $input) {
      sandboxConfig { id name repo harness }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "accountId": "<ACCOUNT_ID>", "name": "repo-fix-preset", "repo": "my-org/my-repo", "harness": "claude_code",
      "sandboxIntegrationIds": ["<SANDBOX_INTEGRATION_ID>"]
    }
  }
  ```
</CodeGroup>

To add an integration to a config that already exists instead of recreating it, use [`addIntegrationToSandboxConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#addintegrationtosandboxconfig). Update or remove either resource later with [`updateSandboxIntegration`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#updatesandboxintegration), [`deleteSandboxIntegration`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#deletesandboxintegration), [`updateSandboxConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#updatesandboxconfig), or [`deleteSandboxConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#deletesandboxconfig). Reference: [`createSandboxIntegration`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#createsandboxintegration), [`createSandboxConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#createsandboxconfig).

## Launch a sandbox job and send it a follow-up message

Launch a job with a prompt, then steer it with a follow-up message while it's running:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation LaunchJob($input: CreateSandboxJobInput!) {
    createSandboxJob(input: $input) { jobId sandboxId }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "spaceId": "<SPACE_ID>", "sandboxConfigId": "<SANDBOX_CONFIG_ID>",
      "initialPrompt": "Investigate the timeout errors from the last 24 hours and propose a fix."
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation FollowUp($input: SendSandboxMessageInput!) {
    sendSandboxMessage(input: $input) { jobId }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "jobId": "<JOB_ID>", "message": "Also check whether the retry wrapper is swallowing the original exception." } }
  ```
</CodeGroup>

Reference: [`createSandboxJob`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#createsandboxjob), [`sendSandboxMessage`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#sendsandboxmessage).

## Snapshot a sandbox as a reusable template

A **Setup Repo** session (`isSetupSession: true` on `createSandboxJob`) clones and configures a repo once so future jobs can boot from the result instead of repeating setup:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation SnapshotTemplate($input: CreateSandboxTemplateInput!) {
    createSandboxTemplate(input: $input) { templateId }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "jobId": "<SETUP_JOB_ID>", "name": "repo-fix-preset-v2" } }
  ```
</CodeGroup>

`templateId` comes back as a string, but `sandboxTemplateId` on `createSandboxConfig`/`updateSandboxConfig` is an `Int` (the underlying DB id), so convert it before linking the template to a config:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation LinkTemplate($input: UpdateSandboxConfigInput!) {
    updateSandboxConfig(input: $input) {
      sandboxConfig {
        id
        activeSandboxTemplate { id name status }
      }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "sandboxConfigId": "<SANDBOX_CONFIG_ID>", "sandboxTemplateId": 2 } }
  ```
</CodeGroup>

Reference: [`createSandboxTemplate`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#createsandboxtemplate), [`updateSandboxConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#updatesandboxconfig).

## Create a cron or metric-triggered automation, then trigger it now

An automation spawns sandbox jobs from a `sandboxConfigId` on a schedule, either a fixed cadence or a metric threshold crossing. Provide exactly one of `cron` or `metric`:

<Tabs>
  <Tab title="Cron">
    ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    mutation CreateCronAutomation($input: CreateAutomationInput!) {
      createAutomation(input: $input) { automationId jobId }
    }
    ```

    ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    {
      "input": {
        "spaceId": "<SPACE_ID>", "name": "nightly-health-check",
        "promptTemplate": "Review the last 24 hours of traces for {{.ProjectName}} and summarize regressions.",
        "sandboxConfigId": "<SANDBOX_CONFIG_ID>", "agentProfile": "default", "harness": "claude_code",
        "cron": { "cadenceSeconds": 86400 }
      }
    }
    ```
  </Tab>

  <Tab title="Metric">
    ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    mutation CreateMetricAutomation($input: CreateAutomationInput!) {
      createAutomation(input: $input) { automationId jobId }
    }
    ```

    ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
    {
      "input": {
        "spaceId": "<SPACE_ID>", "name": "error-rate-spike-triage",
        "promptTemplate": "Error rate crossed threshold for {{.ProjectName}}. Investigate and propose a fix.",
        "sandboxConfigId": "<SANDBOX_CONFIG_ID>", "agentProfile": "default", "harness": "claude_code",
        "metric": {
          "modelId": "<MODEL_ID>", "queryFilter": "attributes[\"status_code\"] = \"ERROR\"",
          "lookbackSeconds": 900, "threshold": 20, "operator": "GT", "evalIntervalSeconds": 300
        }
      }
    }
    ```
  </Tab>
</Tabs>

Fire the automation immediately without waiting for its schedule:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation FireNow($input: TriggerAutomationNowInput!) {
    triggerAutomationNow(input: $input) {
      jobId
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "automationId": "<AUTOMATION_ID>" } }
  ```
</CodeGroup>

`triggerAutomationNow` still runs the normal admission gates (cooloff window, capacity, Signal issue limit), so it can be a no-op for an automation already at its cap. Pause an automation with [`setAutomationEnabled`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#setautomationenabled) (`enabled: false`), repoint it to a different repo with [`setAutomationRepo`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#setautomationrepo) (empty string clears the override), change its schedule with [`updateAutomation`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#updateautomation), or remove it with [`deleteAutomation`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#deleteautomation) (soft-delete). Reference: [`createAutomation`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#createautomation), [`triggerAutomationNow`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#triggerautomationnow).

## Enable Signal on one project, or many at once

Enabling Signal lazily provisions the built-in Signal automation for the project if one doesn't exist yet:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation EnableSignal($input: SetSignalEnabledInput!) {
    setSignalEnabled(input: $input) { ok signalStatus { state cadenceSeconds presetName } }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "modelId": "<MODEL_ID>", "enabled": true } }
  ```
</CodeGroup>

To roll it out across many projects in one call, use `setSignalEnabledBulk`, which processes each project independently and reports per-project outcomes:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation EnableSignalBulk($input: SetSignalEnabledBulkInput!) {
    setSignalEnabledBulk(input: $input) { okCount failedCount results { modelId ok error } }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "modelIds": ["<MODEL_ID_1>", "<MODEL_ID_2>"], "enabled": true } }
  ```
</CodeGroup>

The same bulk call scripted in Python, reading project GIDs from a prior list query:

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import requests

MUTATION = """
mutation EnableSignalBulk($input: SetSignalEnabledBulkInput!) {
  setSignalEnabledBulk(input: $input) {
    okCount failedCount results { modelId ok error }
  }
}
"""

response = requests.post(
    "https://app.arize.com/graphql",
    headers={"x-api-key": "<ARIZE_API_KEY>"},
    json={"query": MUTATION, "variables": {"input": {"modelIds": model_ids, "enabled": True}}},
)
response.raise_for_status()
print(response.json()["data"]["setSignalEnabledBulk"])
```

`llmIntegrationId` on either mutation only applies when `enabled` is true; disabling a project ignores it. Reference: [`setSignalEnabled`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#setsignalenabled), [`setSignalEnabledBulk`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#setsignalenabledbulk).

## Tune Signal's schedule and agent config

Change how often Signal runs and the extra context injected into its prompt:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation TuneSignal($input: UpdateSignalConfigInput!) {
    updateSignalConfig(input: $input) { ok signalStatus { cadenceSeconds additionalContext } }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "modelId": "<MODEL_ID>", "cadenceSeconds": 21600,
      "additionalContext": "This agent is a support bot; treat any answer that promises a refund as high severity."
    }
  }
  ```
</CodeGroup>

`cadenceSeconds` must be between 4 hours (14400) and 30 days (2592000). To run Signal from a custom sandbox config instead of the shared built-in default, attach one:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation AttachSignalConfig($input: SetSignalAgentConfigInput!) {
    setSignalAgentConfig(input: $input) { ok signalStatus { presetName } }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "modelId": "<MODEL_ID>", "sandboxConfigId": "<SANDBOX_CONFIG_ID>" } }
  ```
</CodeGroup>

Revert to the shared default with [`resetSignalAgentConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#resetsignalagentconfig) (`modelId` only); it detaches the custom config without deleting it, so you can reattach it later. Reference: [`updateSignalConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#updatesignalconfig), [`setSignalAgentConfig`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#setsignalagentconfig).

## List Signal issues for a project and resolve or fix one

List the open and ignored issues Signal has filed for a project:

<CodeGroup>
  ```graphql Query theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  query SignalIssuesForProject($modelId: ID!) {
    node(id: $modelId) {
      ... on Model {
        signalIssues(limit: 20) {
          id issueKey title severity status totalMatchCount hasAttachedRepo lastSeen
        }
      }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "modelId": "<MODEL_ID>" }
  ```
</CodeGroup>

Resolve or ignore an issue (or re-open one you dismissed). A resolved issue silently re-opens if the problem recurs; an ignored one stays suppressed across runs:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation ResolveIssue($input: SetSignalIssueStatusInput!) {
    setSignalIssueStatus(input: $input) { signalIssue { id status } }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "id": "<SIGNAL_ISSUE_ID>", "status": "RESOLVED" } }
  ```
</CodeGroup>

When `hasAttachedRepo` is true, launch a fix PR for the issue, borrowing the repo and GitHub credential from the automation that filed it:

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation FixIssue($input: OpenSignalIssuePRInput!) {
    openSignalIssuePR(input: $input) { jobId sandboxId }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  { "input": { "id": "<SIGNAL_ISSUE_ID>" } }
  ```
</CodeGroup>

To just track the issue in GitHub without launching an agent, use [`openSignalIssueGitHubIssue`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#opensignalissuegithubissue) with the same `id` input; it returns the new issue's `issueUrl`. When you're done with Signal on a project entirely, [`deleteSignal`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#deletesignal) removes its automation and is a no-op if none exists. Reference: [`setSignalIssueStatus`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#setsignalissuestatus), [`openSignalIssuePR`](/docs/ax/graphql-reference/mutations/managed-agents-and-signal#opensignalissuepr).

## Gotchas and behavior notes

1. `createAutomation.promptTemplate` is required even when unused: set it to an empty string when `agentTemplateKey` is set, and to a real Go `text/template` string otherwise.
2. `createAutomation` and `updateAutomation` both require exactly one of `cron` or `metric`. Sending both, or neither, is rejected.
3. ID typing is inconsistent: `jobId` is a `String!` on `CreateSandboxTemplateInput` and `SendSandboxMessageInput`, but an `ID!` on `CreateSandboxJobPayload`. `createSandboxTemplate` likewise returns `templateId` as a `String!`, while `sandboxTemplateId` on the config mutations is an `Int`. Convert between them when chaining calls.
4. `setSignalEnabled` and `setSignalEnabledBulk` only apply `llmIntegrationId` when `enabled: true`; disabling ignores it.
5. `UpdateSignalConfigInput.cadenceSeconds` must be between 14400 (4 hours) and 2592000 (30 days).
6. `setAutomationRepo` and the per-automation `repo` on `createAutomation` override the bound `sandboxConfig`'s own `repo`. `SignalStatus.hasAttachedRepo` and `SignalIssue.hasAttachedRepo` reflect this effective, resolved repo, so checking `agentConfig.repo` alone can be wrong.
7. `setSignalIssueStatus`, `openSignalIssuePR`, and `openSignalIssueGitHubIssue` are gated by project-update access on the issue's owning project, not just space membership.
8. `deleteAutomation` and `deleteSignal` are both idempotent: deleting one that's already gone is a no-op rather than an error.
9. The config and integration CRUD inputs accept an optional `spaceId` purely to authorize via space membership; the underlying rows are always account-scoped, not space-scoped.

<CardGroup cols={3}>
  <Card title="Managed agent and Signal mutations" icon="book" href="/docs/ax/graphql-reference/mutations/managed-agents-and-signal" />

  <Card title="All GraphQL mutations" icon="list" href="/docs/ax/graphql-reference/mutations" />

  <Card title="API explorer" icon="terminal" href="/docs/ax/graphql-reference/overview/api-explorer" />
</CardGroup>