FruxonDocs
Agent NetworkTriggers

Tests one stage of the automation on one input.

Queues a sandbox run of the stage's agent, on its deployed revision, with exactly the request a pass would send, and returns at once; poll the test until it finishes. The input is a real item (only read), a record the source returned, typed data, or the step before in a walk. Each connection reads for real and writes to the simulator unless routed to the simulator entirely; a live connection is not offered. The run is charged to the agent's test budget. Returns 400 when the stage cannot be tested yet — not a PROCESS stage, a batch stage, an undeployed agent, or an agent holding a tool that would reach a real person — and 409 when the caller already has the most tests running at once.

POST
/v1/tenants/{tenant}/triggers/{trigger}/stageTests

Authorization

Bearer
AuthorizationBearer <token>

JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token.

In: header

Path Parameters

trigger*string

The trigger identifier.

Formatuuid
tenant*string

The tenant identifier

Request Body

The stage, the input, and how to reach each connection.

stageIndex?integer|null

The stage to run, by its position in the shape — a stage being edited may have no id yet. Required unless the seed continues from a previous step, which defaults to the stage that step advanced into.

Formatint32
workShape?

The shape to test, when it is a draft the editor has not saved; the automation's saved shape otherwise.

seed?

Where the stage's input comes from. Exactly one source.

rewind?boolean

For a real item only: remove what the tested stage and every later stage declare they produce, and what the item's history records them writing, so a stage re-tested on an item that has moved past it does not read its own earlier answer. On by default.

routing?|null

How to reach each of the stage agent's connections, by connection id: SIMULATED or READ_THROUGH. A connection not named here reads for real and writes to the simulator, unless it already has a sandbox of its own saved. A live connection is never offered: a write a test makes is not a ledger effect, so the real run would make it again.

walkId?string|null

The walk to add this test to, when it re-runs a step of one rather than continuing it.

Formatuuid
step?integer|null

Which step of Fruxon.Model.ItemLedgers.CreateLedgerStageTestRequest.WalkId this test re-runs. Requires Fruxon.Model.ItemLedgers.CreateLedgerStageTestRequest.WalkId.

Formatint32
reply?string|null

At an ASK stage, the reply a person would send — prose or an {"answers":{...}} payload — read the way a real reply is read. Required there, and refused at any other stage.

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/tenants/string/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08/stageTests" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "00000000-0000-0000-0000-000000000000",
  "walkId": "00000000-0000-0000-0000-000000000000",
  "step": 0,
  "previousTestId": "00000000-0000-0000-0000-000000000000",
  "stageIndex": 0,
  "stageId": "string",
  "stageName": "string",
  "status": "QUEUED",
  "seedKind": "ITEM",
  "seedItemId": "00000000-0000-0000-0000-000000000000",
  "itemKey": "string",
  "fromDraft": false,
  "input": null,
  "userQuery": "string",
  "reply": "string",
  "agentId": "string",
  "agentRevision": 0,
  "routingDefault": "NONE",
  "routingOverrides": {},
  "executionRecordId": "00000000-0000-0000-0000-000000000000",
  "output": "string",
  "verdict": {
    "kind": "ADVANCE",
    "toStatus": "READY",
    "cause": "string",
    "detail": "string",
    "failedCheck": "RUN",
    "attempt": 0,
    "maxAttempts": 0,
    "nextStageId": "string",
    "routed": false,
    "produced": null,
    "dataAfter": null,
    "dedupeKey": "string",
    "dedupeKeyIncomplete": false,
    "duplicateOf": "string",
    "nextStageMissing": [
      "string"
    ],
    "sink": {
      "stageId": "string",
      "kinds": [
        "UNSPECIFIED"
      ],
      "target": "string"
    }
  },
  "simulatedCalls": [
    {
      "integrationId": "string",
      "toolKey": "string",
      "operation": "CREATE",
      "simulatedEntityId": "00000000-0000-0000-0000-000000000000",
      "createdAt": 0
    }
  ],
  "cost": 0,
  "durationMs": 0,
  "warnings": [
    "string"
  ],
  "createdAt": 0,
  "completedAt": 0,
  "expiresAt": 0
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
Empty
Empty
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Stops a stage test whose run has not ended.

Cancels the run and keeps the test, so what was started stays readable. Returns 409 when the test has already ended.

Lists recent source events for an unsaved trigger draft.

Returns the last N items the source mailbox or workspace would have matched, annotated with whether the draft filter would have fired on each. This backs the create-flow panel before a trigger row exists. It is read-only — no upstream writes, no trigger persistence, no agent enqueue. The capability is per-`(integration, eventType)`; pairs without a registered `IRecentEventSource` return 400. See `docs/design/agent-network.md §13`.