Agents

Overview

An agent represents one prompt execution and owns its full lifecycle. Its API record contains the configuration used for the run and the data produced during execution. This data includes the trace, executor result, auditor summary, findings, and artifacts.

Create an agent directly when the configuration applies to one run. Running a test spawns an agent from a saved configuration. The spawned agent links back to that test, while its state and results belong to the agent.

Lifecycle

The status field reports the current state:

• pending: The run waits for an executor.
• running: The executor performs the prompt.
• waiting: The executor waits for human input or browser handoff.
• auditing: The executor finished, and the auditor reviews the evidence.
• completed: The run and audit finished. This state can include application findings.
• failed: A platform error prevented the run or audit from finishing.
• stopped: A user or the platform stopped the run.

Lifecycle status and test outcome serve different purposes. The result.success field gives the final pass or fail value.

Audit and summary

The executor stores result when it finishes the prompt, then moves the agent from running to auditing. The result contains the executor's reported success, short summary, and optional report.

During auditing, a separate, heavier model checks the execution trace and supporting evidence. The summary object stores the auditor's output, including the outcome, reason, test steps, decision factors, findings, and report. The auditor can also correct result.success.

Capabilities

Browser agents can use these main capabilities:

• Browser interaction. Agents can navigate, read pages, take screenshots, inspect accessibility data, and use common page controls.
• Low-level input. Agents can use pointer actions, keyboard actions, drag actions, key combinations, and scroll gestures.
• HTTP requests. Agents can send HTTP requests without using the browser.
• File workspace. Each agent has an isolated workspace. It can manage files and upload them through page controls.
• JavaScript diagnostics. Agents can run read-only JavaScript to inspect browser state. They cannot use it to perform page actions.
• Console and network inspection. Agents can inspect browser console messages and network events.
• Human handoff. Agents can pause and give browser control to a user. They resume after the user returns control.

List agents

Returns tenant-owned runs in descending ID order.

Parameters

Example Request

curl "http://app.aiqaramba.com/api/v1/agents" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)

Create an agent

Creates and queues an agent from inline instructions.

Request Body (application/json)

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/agents" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "<uuid>",
    "instructions": "<string>"
  }'

Status Codes

Response Fields (201)

Get an agent

Parameters

Example Request

curl "http://app.aiqaramba.com/api/v1/agents/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)

Delete an agent

Parameters

Example Request

curl -X DELETE "http://app.aiqaramba.com/api/v1/agents/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Respond to an agent clarification

Appends a function response and resumes an agent waiting for human clarification.

Parameters

Request Body (application/json)

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/agents/<id>/clarification" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "response": "<string>"
  }'

Status Codes

Response Fields (200)

Upload files to an agent workspace

Delivers files to a pending, running, or waiting agent workspace.

Parameters

Request Body (multipart/form-data)

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/agents/<id>/files" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -F 'files=@./files'

Status Codes

Response Fields (200)

Retry an agent

Clones a terminal or recoverable run and queues the clone while preserving the original.

Parameters

Request Body (application/json)

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/agents/<id>/retry" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<string>",
    "max_iterations": 1,
    "browser_type": "<string>"
  }'

Status Codes

Response Fields (201)

Stop an agent

Cancels active jobs and atomically finalizes a pending, running, or waiting agent as stopped.

Parameters

Example Request

curl -X POST "http://app.aiqaramba.com/api/v1/agents/<id>/stop" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Response Fields (200)