Get started with Agent Builder

Use this walkthrough to start an Agent Builder session, poll until the build finishes, and run the saved Agent.

Agent Builder is currently single-shot. Put the full request in your first prompt: URL, fields, pagination, authentication needs, output shape, and anything to skip.

Before you start

Generate an API key from your Sequentum dashboard, then choose the prompt you want to send.

import os
os.environ["SEQUENTUM_API_KEY"] = "sk-..."

process.env.SEQUENTUM_API_KEY = "sk-...";

export SEQUENTUM_API_KEY="sk-..."

Start Agent Builder

Send your prompt to Agent Builder. Replace the URL and fields with your target; the response returns a sessionId.

import os
import requests

prompt = "Get the shoe information from https://training.sequentum.com/ShoeStore/product.html?id=1"

response = requests.post(
    "https://dashboard.sequentum.com/api/v1/agent-builder/start",
    headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
    json={"prompt": prompt},
)

session = response.json()
print(session["sessionId"])

const prompt =
  "Get the shoe information from https://training.sequentum.com/ShoeStore/product.html?id=1";

const response = await fetch(
  "https://dashboard.sequentum.com/api/v1/agent-builder/start",
  {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ prompt }),
  }
);

const session = await response.json();
console.log(session.sessionId);

export SEQUENTUM_API_KEY="sk-..."

curl "https://dashboard.sequentum.com/api/v1/agent-builder/start" \
  -X POST \
  -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Get the shoe information from https://training.sequentum.com/ShoeStore/product.html?id=1"
  }'

Wait for the agent to build

Poll the session until status is completed. The completed response includes the saved Agent id.

import os
import time
import requests

session_id = "ab_123..."

while True:
    response = requests.get(
        f"https://dashboard.sequentum.com/api/v1/agent-builder/{session_id}/status",
        headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
    )
    body = response.json()

    if body["status"] == "completed":
        agent_id = body.get("agentId") or body["configId"]
        print(f"Agent built: {agent_id}")
        break

    if body["status"] == "error":
        raise RuntimeError(body.get("error", "build failed"))

    time.sleep(5)

const sessionId = "ab_123...";

let agentId: number | undefined;

while (!agentId) {
  const response = await fetch(
    `https://dashboard.sequentum.com/api/v1/agent-builder/${sessionId}/status`,
    { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
  );

  const body = await response.json();

  if (body.status === "completed") {
    agentId = body.agentId ?? body.configId;
    console.log(`Agent built: ${agentId}`);
    break;
  }

  if (body.status === "error") {
    throw new Error(body.error ?? "build failed");
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

export SESSION_ID="ab_123..."

while true; do
  RESPONSE=$(curl -s "https://dashboard.sequentum.com/api/v1/agent-builder/$SESSION_ID/status" \
    -H "Authorization: ApiKey $SEQUENTUM_API_KEY")

  STATUS=$(echo "$RESPONSE" | jq -r .status)

  if [ "$STATUS" = "completed" ]; then
    AGENT_ID=$(echo "$RESPONSE" | jq -r '.agentId // .configId')
    echo "Agent built: $AGENT_ID"
    break
  fi

  if [ "$STATUS" = "error" ]; then
    echo "$RESPONSE"
    exit 1
  fi

  sleep 5
done

Start a Run

Start the saved Agent asynchronously. The response returns a Run id you can poll.

import os
import requests

agent_id = "12345"

response = requests.post(
    f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/start",
    headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
    json={"isRunSynchronously": False},
)

run = response.json()
run_id = run["id"]
print(run_id)

const agentId = "12345";

const response = await fetch(
  `https://dashboard.sequentum.com/api/v1/agent/${agentId}/start`,
  {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ isRunSynchronously: false }),
  }
);

const run = await response.json();
const runId = run.id;
console.log(runId);

export SEQUENTUM_API_KEY="sk-..."
export AGENT_ID="12345"

RUN_ID=$(curl -s "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/start" \
  -X POST \
  -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isRunSynchronously": false }' | jq -r .id)

echo "$RUN_ID"

Wait for the Run

Poll run status until the Run is finished. Completed and Success mean the Run finished successfully.

import time

FINISHED = {6, 8, 9, 10, 11, "Failure", "Stopped", "Completed", "Success", "Skipped"}
SUCCESSFUL = {9, 10, "Completed", "Success"}

while True:
    response = requests.get(
        f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/run/{run_id}/status",
        headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
    )
    run = response.json()

    if run["status"] in FINISHED:
        if run["status"] not in SUCCESSFUL:
            raise RuntimeError(f"Run did not complete successfully: {run}")
        break

    time.sleep(5)

const finished = new Set([6, 8, 9, 10, 11, "Failure", "Stopped", "Completed", "Success", "Skipped"]);
const successful = new Set([9, 10, "Completed", "Success"]);

while (true) {
  const response = await fetch(
    `https://dashboard.sequentum.com/api/v1/agent/${agentId}/run/${runId}/status`,
    { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
  );
  const run = await response.json();

  if (finished.has(run.status)) {
    if (!successful.has(run.status)) {
      throw new Error(`Run did not complete successfully: ${JSON.stringify(run)}`);
    }
    break;
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

while true; do
  RUN=$(curl -s "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/run/$RUN_ID/status" \
    -H "Authorization: ApiKey $SEQUENTUM_API_KEY")
  STATUS=$(echo "$RUN" | jq -r .status)

  case "$STATUS" in
    9|10|Completed|Success)
      break
      ;;
    6|8|11|Failure|Stopped|Skipped)
      echo "$RUN"
      exit 1
      ;;
  esac

  sleep 5
done

List output files

After the Run finishes, list its output files and choose a file to download.

files_response = requests.get(
    f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/run/{run_id}/files",
    headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
)
files = files_response.json()
file_id = files[0]["id"]
file_name = files[0].get("name") or f"run-{run_id}-output"

const filesResponse = await fetch(
  `https://dashboard.sequentum.com/api/v1/agent/${agentId}/run/${runId}/files`,
  { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
);
const files = await filesResponse.json();
const fileId = files[0].id;
const fileName = files[0].name ?? `run-${runId}-output`;

FILES=$(curl -s "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/run/$RUN_ID/files" \
  -H "Authorization: ApiKey $SEQUENTUM_API_KEY")

FILE_ID=$(echo "$FILES" | jq -r '.[0].id')
FILE_NAME=$(echo "$FILES" | jq -r '.[0].name // "run-output"')

Download an output file

Download endpoints redirect to the file content. Follow redirects when saving the file.

download_response = requests.get(
    f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/run/{run_id}/file/{file_id}/download",
    headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
)

with open(file_name, "wb") as f:
    f.write(download_response.content)

import { writeFile } from "node:fs/promises";

const downloadResponse = await fetch(
  `https://dashboard.sequentum.com/api/v1/agent/${agentId}/run/${runId}/file/${fileId}/download`,
  { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
);

await writeFile(fileName, Buffer.from(await downloadResponse.arrayBuffer()));

curl -L "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/run/$RUN_ID/file/$FILE_ID/download" \
  -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
  -o "$FILE_NAME"

Runs can produce multiple output files. List files again if the Agent writes separate datasets or downloads source files.

What success looks like

When the build finishes, Agent Builder gives you a saved Agent. A good first build has:

A clear Agent name and description.
Fields that match your prompt.
A test run with records shaped like the entity you asked for.

For the ShoeStore prompt, the output file should contain records like this:

[
  {
    "name": "Trail running shoe",
    "price": "$89.99",
    "sku": "SHOE-001",
    "availability": "In stock",
    "productUrl": "https://training.sequentum.com/ShoeStore/product.html?id=1"
  }
]

If the records are missing a field or include the wrong items, start a new build with a tighter prompt. Mention the missing field, the page pattern, and the section or records to skip.

Write a good prompt

Lead with the URL

Start with the exact page or site section: “Extract product data from https://....”

Mention pagination explicitly

Say “follow all paginated pages” or “first 50 pages only” — Agent Builder will scope the run.

Specify the output shape

Agent Builder can infer a schema, but naming fields gives you more predictable output. Ask for “one row per product” or “one row per invoice” when the page contains repeated records.

What’s next

Agent Builder sessions

Understand session status, stopping a build, and the handoff to the saved Agent.

Schedule recurring runs

Run the saved Agent automatically on a cadence you define.

Get started

Agent Builder

MCP

Agents

Control Center

Resources

Before you start

Start Agent Builder

Wait for the agent to build

Start a Run

Wait for the Run

List output files

Download an output file

What success looks like

Write a good prompt

What’s next

Agent Builder sessions

Schedule recurring runs

​Before you start

​Start Agent Builder

​Wait for the agent to build

​Start a Run

​Wait for the Run

​List output files

​Download an output file

​What success looks like

​Write a good prompt

​What’s next

Agent Builder sessions

Schedule recurring runs

Before you start

Start Agent Builder

Wait for the agent to build

Start a Run

Wait for the Run

List output files

Download an output file

What success looks like

Write a good prompt

What’s next