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

# Get started with Agent Builder

> Build a working extraction Agent from a prompt through the API.

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

<Note>
  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.
</Note>

## Before you start

Generate an API key from your [Sequentum dashboard](https://dashboard.sequentum.com/user/api-keys), then choose the prompt you want to send.

<CodeGroup>
  ```python Python theme={null}
  import os
  os.environ["SEQUENTUM_API_KEY"] = "sk-..."
  ```

  ```ts TypeScript theme={null}
  process.env.SEQUENTUM_API_KEY = "sk-...";
  ```

  ```bash cURL theme={null}
  export SEQUENTUM_API_KEY="sk-..."
  ```
</CodeGroup>

## Start Agent Builder

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

<CodeGroup>
  ```python Python theme={null}
  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"])
  ```

  ```ts TypeScript theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

## Wait for the agent to build

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```ts TypeScript theme={null}
  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));
  }
  ```

  ```bash cURL theme={null}
  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
  ```
</CodeGroup>

## Start a Run

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```ts TypeScript theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

## Wait for the Run

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```ts TypeScript theme={null}
  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));
  }
  ```

  ```bash cURL theme={null}
  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
  ```
</CodeGroup>

## List output files

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

<CodeGroup>
  ```python Python theme={null}
  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"
  ```

  ```ts TypeScript theme={null}
  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`;
  ```

  ```bash cURL theme={null}
  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"')
  ```
</CodeGroup>

## Download an output file

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```ts TypeScript theme={null}
  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()));
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

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

## 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:

```json theme={null}
[
  {
    "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

<AccordionGroup>
  <Accordion title="Lead with the URL">
    Start with the exact page or site section: "Extract product data from `https://...`."
  </Accordion>

  <Accordion title="Mention pagination explicitly">
    Say "follow all paginated pages" or "first 50 pages only" — Agent Builder will scope the run.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Agent Builder sessions" icon="clock" href="/agent-builder/sessions">
    Understand session status, stopping a build, and the handoff to the saved Agent.
  </Card>

  <Card title="Schedule recurring runs" icon="calendar" href="/concepts/schedules">
    Run the saved Agent automatically on a cadence you define.
  </Card>
</CardGroup>