Getting started with the Step AI Agent

The Step AI Agent ships as a Step Automation Package. You give it the test cases to produce, and collect a finished and validated package when it completes. You choose how you interact with it.

Choose your path

The three paths below run the same workflow and produce the same automation package.

Work from Execution Best for
Step Studio Local A visual UI for defining test cases, launching runs and reading reports, with no command line
IDE Local Working in your own toolchain, on your existing code base
Step Platform Central Running with nothing installed locally, on shared infrastructure, with agentic and automation results visible to the whole team

Before you start

Check the CLI version. The agent needs the Step CLI from Step 31 or later: step --version must report 3.31.0 or above.

Point it at a test environment. The agent explores a running application, so anything that application can display may reach the model, and it completes the journeys it builds. Use synthetic data and test accounts, and keep the API key out of anything you commit. Data and privacy covers what leaves your environment, what does not, and what you control.

Step Studio

Step Studio is a local visual editor for automation packages, and it launches the agent on your own machine. Because the run happens locally, the agent can work from the test cases you already hold.

Installation

Step Studio is distributed with the Step CLI, so there is nothing separate to acquire. Step Studio covers the editor itself; this section covers only what the agent adds to it. You need:

  • The Step CLI 3.31 or later. It includes Step Studio, and the agent calls it to run the automation it has generated.
  • Node.js 24 or newer on your machine
  • The Step AI Agent itself: a standalone jar, published as a Step Enterprise artifact at distribution:step-ai-agents on our Nexus. There is no installer — you download the jar and point Studio at it. Enterprise customers receive their Nexus credentials from Step support on request: see Access enterprise download section.
  • An Anthropic API key

The Step Node.js agent, which the generated keywords run on, ships inside the CLI and is extracted on first use. There is nothing to install or start separately.

Point Studio at the agent package and export the key, rather than committing it anywhere. The agent Studio launches inherits both:

export STEP_STUDIO_AI_AGENT_PACKAGE=/path/to/step-ai-agents.jar
export ANTHROPIC_API_KEY=sk-ant-...

Give the package an absolute path. Studio reads the variable once, at startup, so set it before launching: exporting it in a shell where Studio is already running changes nothing until you restart it.

Then start Studio:

step studio       # serves the UI on http://localhost:8080

Use step studio open -d <dir> to load a particular package, and type q in its terminal to shut down.

Quick start

  1. Create a New package.
  2. Choose Create with AI.
  3. Give the test case a name and a description of the behaviour to automate: the steps, the preconditions and the expected outcome. Both are required. Test-specific instructions is optional, for constraints such as a selector convention to follow. If you already hold a written specification, paste it under Paste a specification instead.
  4. Click Generate test cases. Studio generates into the package you are working in, so there is no output location to set, and shows the report when the run finishes.
The Generate screen in Step Studio, reached from AI Generate in the left-hand navigation, holding the Wikipedia example from this page. Select how to generate offers Describe Your Goal or Define Test Cases, with Define Test Cases selected. One test case card, marked Complete, holds a required Test case name reading wikipedia_black_hole and a required Test description reading Go to the Black hole article and assert the title is Black hole. A Form and Markdown toggle sits above the card, an Add test case button below it, and Advanced options for shared automation instructions at the foot. A Generate test cases button sits at the top right.
  1. Deploy or execute the package centrally (optional), on the Step Platform. Set stepUrl and token in ~/stepcli.properties and restart Studio to connect it.

See Configuration for every field and parameter, and Agentic test automation with Step Studio for a worked example end to end.

IDE

The Step CLI runs the agent on your own machine, driven from your IDE or a CI/CD job. Because the agent runs where your code is, it can work from your existing code base and test assets.

Installation

You need:

Export the key in the shell or job that runs it, rather than committing it anywhere:

export ANTHROPIC_API_KEY=sk-ant-...

Quick start

A complete run, small enough to try as it stands:

step ap execute --local \
  --package=/path/to/step-ai-agent \
  --includePlans="AI Agent - Automate" \
  -ep 'apDirectory=/path/to/your-package|instructions={"testCases":[{"name":"wikipedia_black_hole","spec":"Go to https://en.wikipedia.org/wiki/Black_hole and assert the title is Black hole.","mode":"create"}]}'

The two paths do different jobs: --package is the agent you downloaded, and apDirectory is where the package it generates will be written.

Execution parameters are passed with -ep, separated by |. Quote the whole value with single quotes, so the JSON keeps its double quotes. The command blocks until the run ends and prints the report tree.

To run centrally instead, drop --local and name the instance and an API key. This gains parallel execution, a separately provisioned environment and real infrastructure, flakiness detection across repeated runs, and centralized logging other teams can see:

step ap execute \
  --stepUrl=https://your-step-instance \
  --token="$STEP_API_KEY" \
  --package=/path/to/step-ai-agent \
  --includePlans="AI Agent - Automate" \
  -ep 'apDirectory=/path/to/your-package|instructions={"testCases":[{"name":"wikipedia_black_hole","spec":"Go to https://en.wikipedia.org/wiki/Black_hole and assert the title is Black hole.","mode":"create"}]}'

A central run needs more of the instance than a local one, and takes the Anthropic key from a Step Parameter rather than the environment: see Step Platform.

See Configuration for every field and parameter, and Agentic test automation from the command line for a worked example end to end.

Step Platform

The agent is itself an Automation Package, so a Step instance runs it the way it runs any other. Deployed once, it serves everyone who can reach the instance, with nothing installed on their machines.

Installation

You need:

  • A Step instance, version 31 or later, running in a SaaS cluster or on-premises. The agent needs Step CLI 3.31, and the CLI should match the version of the server it operates.
  • A connected Step Node.js agent, available throughout the run. The agent’s keywords are Node keywords and execute nowhere else.
  • Node.js 24 or newer and the Step CLI 3.31 or later on the machine running that agent
  • The Step AI Agent itself, deployed to the instance

Getting the jar works as it does for the other two paths: download it from distribution:step-ai-agents on our Nexus, with credentials Step support provides on request, see Access enterprise download section. Then deploy it to the instance as an ordinary Automation Package — Upload Automation Package covers the dialog. The same dialog also accepts Maven coordinates, which avoids the download-and-upload round trip where the instance can reach the repository itself.

On an instance the Anthropic key is a Step Parameter named ANTHROPIC_API_KEY rather than an environment variable. Set its scope to Global so it reaches every keyword of the run, and mark it Protected so the value is obfuscated in the UI, reports and exports. One definition covers the whole run, and the run log records which source was resolved, so a missing key is visible before the first model call fails.

Quick start

Deploying the agent puts its plan, AI Agent - Automate, in the instance’s Plans list. You run it from there, like any other plan:

  1. Open Plans and find AI Agent - Automate.
  2. Click the play button to open the execution panel.
  3. Set apDirectory and instructions as execution parameters — the same two values the local paths pass with -ep. See Execution parameters for the full list.
  4. Run it. The agent’s own workflow becomes an ordinary Step execution, one node per phase, which you follow and inspect like any other.

What it produces is a package too, so the results land where the rest of your automation already reports.

What you get

The run publishes to apDirectory the finished package and the material it produced on the way there:

  • The automation package. The test plans, the keyword declarations and their implementation. It runs on Step without the agent.

    The plan generated from the example above, with each step named in the words you used, and stamped with the run that produced it:

    plans:
  - name: "demo_wikipedia_article"
    metadata:
      origin: ai
      ai:
        executionId: "6ac4fc4f09314a0cdb189814"
    root:
      testCase:
        nodeName: "demo_wikipedia_article"
        children:
          - callKeyword:
              nodeName: "Navigate to the article URL"
              keyword: "openWikipediaArticle"
          - callKeyword:
              nodeName: "Verify the first heading reads the expected title"
              keyword: "verifyArticleTitle"

    And an extract from the keywords it calls. Each one performs its step and asserts the outcome it owns, records what it observed, and attaches a trace:

    export async function verifyArticleTitle(input, output, session, properties) {
    const expectedTitle: string = input?.expectedTitle ?? DEFAULT_EXPECTED_TITLE;
    const { context, page } = requirePage(session);
    await startTracing(context);
    try {
        const heading = page.getByRole('heading', { level: 1 });
        await heading.waitFor({ state: 'visible' });
        const actual = (await heading.innerText()).trim();
        output.add('actualTitle', actual);
        if (actual !== expectedTitle) {
            throw new Error(`Expected first heading "${expectedTitle}" but found "${actual}"`);
        }
    } finally {
        await safeStopTracing(context, output, 'verifyArticleTitle');
    }
}

  • The keyword specification. How each step is to be driven, written and reviewable before any code existed.

  • The request, verbatim. The instructions exactly as you gave them, so the same run can be repeated later.

  • The report. The verdict, what each test case was verified by, how well the plan covered the request, and what the run cost in time and money.

  • Logs and traces, one set per phase, including the browser trace from the exploration and the log of the execution.

A run that fails publishes to a sibling directory instead, so a previously working package is never overwritten.

Troubleshooting

no handler for NodeFunctionType. No Node.js agent is available. On a central run the instance has none connected, or it is down. The agent’s keywords are Node keywords and execute nowhere else.

doesn't contain the AP descriptor file. --package is pointing at a directory holding no automation-package.yaml. It must point at the Step AI Agent’s own package, not at the package you are generating.

A green pipeline that publishes no test results. --reportDir is not where the JUnit file lands: the report is written into a timestamped subdirectory of it, such as reports/20261007-153122-453428-junit/20261007-153122-453428-junit.xml. A collector matching reports/*.xml therefore matches nothing and the job passes while reporting nothing. Match reports/**/*.xml instead.

The report generation is not supported for local execution. --reportType cannot be combined with --local; the command exits 1. A local run still signals its verdict through its exit code, so it can gate a build, but it cannot produce a report file. Run the package on an instance when a report is needed.

Version mismatch. The server version (x) is incompatible with the current CLI version (y). The CLI refuses to drive an instance on a different minor version. It checks before uploading anything, so the target project is left untouched. Use a version-matched instance; --force skips the check but overrides a deliberate guard.

has mode "extends", but no test case matching that name exists in the reused codebase. The name you gave does not match any test case in the package being extended. Check specs/plan.yaml for the name the package actually holds. The run stops in its first phase, before any model work, so nothing is spent.

Authentication errors from the model calls. ANTHROPIC_API_KEY was found in neither the Step Parameter nor the environment of the process running the agent. The run log records which source it resolved, and warns when the parameter is missing.

The run stops when the generated package is executed. The Step CLI is missing from the PATH of the machine running the agent. The agent calls it to run the automation it has just generated, so the run fails at that point rather than at startup. A healthy local execution logs Local execution supports the following agent types: Node.js, Java.

Data and privacy

The agent sends content from the system under test to a large language model. Before pointing it at an application that holds real data, read Data and privacy.

Next steps

Follow a worked end-to-end example, in whichever role fits your work:

Both cover the same scenario and can be followed independently.