FruxonDocs
AgentsExecution

Test an agent with a draft revision

Executes the agent using a specific draft revision for testing purposes. This allows validating changes before publishing.

API-Only Endpoint

This endpoint is available via API only and requires authentication using the X-API-KEY header. Fill in your parameters below and the code samples will update automatically. To generate an API key, see the Settings guide.

POST
/v1/tenants/{tenant}/agents/{agent}:test

Authorization

Bearer ApiKey
AuthorizationBearer <token>

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

In: header

X-API-KEY<token>

API key passed in the X-API-KEY header. Generate one from the Fruxon settings.

In: header

Path Parameters

agent*string

The unique identifier of the agent

tenant*string

The tenant identifier

Request Body

The test request including revision and parameters

assets?|null

Assets (files / knowledge sources) made available to the draft flow for this test run.

flow?

Represents a sequence of steps in a agent flow, supporting versioning and ordered execution.

A valid flow has exactly one ENTRY_POINT step and exactly one EXIT_POINT step in Steps — these are not synthesized for you. The other steps (AGENT, TOOL, CLAUDE_BOX) sit between them, wired by Edges.

parametersMetadata?|null

The parameter schema for this test run — name, type, required-ness, default values. This is the authoritative declaration the engine uses to resolve {{param.x}} placeholders against Parameters at run time.

EntryPointFlowStep.parameters on the flow holds the same shape and serves the UI / agent introspection; the runtime reads the request-level parametersMetadata here. For consistency, populate both with the same list.

subAgents?|null

List of additional sub-abents used by the flow during execution. These are referenced from within steps in the flow.

parameters?|null

Key-value pairs of actual input values provided for the parameters.

attachments?|null

File attachments included with the test request.

integrationConfigs?|null

Integration configs to use for this test run, overriding the ones pinned on the draft revision. Lets the caller swap in different credentials or routing without modifying the draft.

integrationBindings?|null

Agent-wide default integration config per integration id used for this test run. See Fruxon.Model.Agents.AgentRevision.IntegrationBindings.

llmConfigs?|null

LLM provider configurations (API keys, etc.) to use for this test.

baseRevision?integer

Number of the existing agent revision this draft is based on — the test run resolves masked secrets (API keys, credentials) by looking them up in that revision's stored integrationConfigs / llmConfigs.

Set to 0 (the default) when there is no base revision — e.g. a brand-new agent with no published revision yet. With 0, no secret resolution happens; any config the draft references must carry its secrets inline.

Formatint64
mode?string

Selects which integration-config variant an execution uses. Sandbox falls back to production per-config when no sandbox variant is configured. Callers normally send PRODUCTION or SANDBOX; UNSPECIFIED is the zero value and exists only so the field can be omitted on the wire without misrepresenting the user's intent — the host DTO supplies the real default (typically PRODUCTION).

Value in"UNSPECIFIED" | "PRODUCTION" | "SANDBOX"
sessionId?string|null

Optional session ID to use for testing. If null, a new session may be generated.

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/tenants/string/agents/string:test" \  -H "Content-Type: application/json" \  -d '{}'
{
  "response": "string",
  "trace": {
    "agentId": "string",
    "agentRevision": 0,
    "createdAt": 0,
    "parameters": {},
    "startTime": 0,
    "endTime": 0,
    "duration": 0,
    "traces": [
      {
        "id": "string",
        "displayName": "string",
        "type": "UNSPECIFIED",
        "llmStepTrace": null,
        "toolTrace": null,
        "hitlTrace": null,
        "steps": [],
        "result": null,
        "status": "UNSPECIFIED",
        "error": "string",
        "startTime": 0,
        "endTime": 0,
        "duration": 0
      }
    ],
    "result": {
      "strValue": "string",
      "jsonValue": null,
      "fileLink": "string"
    },
    "inputCost": 0,
    "outputCost": 0,
    "totalCost": 0
  },
  "sessionId": "string",
  "links": [
    {
      "fileId": "string",
      "fileType": "string",
      "promptLink": "<string:string/>"
    }
  ],
  "executionRecordId": "00000000-0000-0000-0000-000000000000",
  "status": "COMPLETED",
  "humanApprovalRequestId": "00000000-0000-0000-0000-000000000000"
}
{
  "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
}

Test an agent with a draft revision via SSE streaming

Streams a draft-revision test run as Server-Sent Events (SSE) — the same event protocol as `:stream`, but executed against the inline draft flow in the request rather than a published revision.

Gets per-environment execution summaries for an agent.

Returns aggregated execution count, total cost, and last activity time for each environment that has execution records for this agent.