Skip to content
Agent as a BusinessAgent as a Business Documentation

Preview an unsaved Single Agent Definition

POST
/api/app/{app_slug}/single-agent/preview/
curl --request POST \
  --url https://api.agentaab.com/api/app/example/single-agent/preview/ \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "definition": { "kind": "single_agent", "version": 1, "interaction_mode": "completion", "instructions": { "system": "example", "user_template": "example" }, "model": { "provider": "example", "model": "example", "credential_ref": "example", "api_base": "https://example.com", "temperature": 1, "top_p": 1, "frequency_penalty": 1, "presence_penalty": 1 }, "tools": [ { "id": "example", "kind": "mcp", "version": "example", "tool_name": "example", "endpoint": "https://example.com", "credential_ref": "example", "credential_mode": "bearer" } ], "input_schema": {}, "output_schema": {}, "limits": { "timeout_ms": 1, "max_output_tokens": 1, "max_tool_calls": 1 }, "configuration": {} }, "inputs": {} }'

Execute the submitted Definition and structured inputs without persisting the Draft or changing the active Capability Release. The response contains only a sanitized result and trace summary.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
app_slug
required
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
definition
required

Complete authoritative editable Definition for one Single Agent. Raw secret-like fields and values are rejected recursively.

object
kind
required
string
Allowed values: single_agent
version
required
integer
Allowed values: 1
interaction_mode
required
string
Allowed values: completion chat
instructions
required
object
system
required
string
<= 32000 characters
user_template
required
string
>= 1 characters <= 64000 characters
model
required
object
provider
required
string
>= 1 characters <= 100 characters
model
required
string
>= 1 characters <= 200 characters
credential_ref
string
/^[A-Z][A-Z0-9_]{2,127}$/
api_base

Optional absolute HTTPS provider endpoint without userinfo or secret query parameters.

string format: uri
temperature
required
number
<= 2
top_p
required
number
<= 1
frequency_penalty
required
number
>= -2 <= 2
presence_penalty
required
number
>= -2 <= 2
tools
required
Array<object>
<= 32 items

A pinned Tool identity and optional server-managed credential reference. Raw credential values are forbidden.

object
id
required
string
kind
required
string
Allowed values: mcp function
version
required
string
tool_name
required
string
endpoint

Exact absolute HTTPS endpoint. Required for MCP Tools.

string format: uri
credential_ref

Name of a server-side Worker secret binding, never a credential value.

string
/^[A-Z][A-Z0-9_]{2,127}$/
credential_mode
string
Allowed values: bearer x_api_key
input_schema
required

JSON Schema with an object root.

object
key
additional properties
any
output_schema
required

JSON Schema with an object root.

object
key
additional properties
any
limits
required
object
timeout_ms
required
integer
>= 1000 <= 120000
max_output_tokens
required
integer
>= 1 <= 32768
max_tool_calls
required
integer
<= 32
configuration
required
object
key
additional properties
any
inputs
required
object
key
additional properties
any

Responses

Section titled “Responses”

200

Section titled “200”

The unsaved Definition executed successfully with source single_agent_unsaved_preview.

Media typeapplication/json
object
success
required
boolean
source
string
Allowed values: single_agent_unsaved_preview
execution_id
required
string
result
object
key
additional properties
any
error
string
code
string
trace
required
object
status
required
string
Allowed values: succeeded failed
duration_ms
required
integer
provider
required
string
model
required
string
interaction_mode
required
string
Allowed values: completion chat
http_status
integer
>= 100 <= 599
Example
{
  "source": "single_agent_unsaved_preview",
  "trace": {
    "status": "succeeded",
    "interaction_mode": "completion"
  }
}

400

Section titled “400”

The Definition or structured inputs are invalid.

Media typeapplication/json
object
error
required
string
code
string
draft_revision
string
issues
Array<object>
object
code
required
string
path
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "code": "example",
  "draft_revision": "example",
  "issues": [
    {
      "code": "example",
      "path": "example",
      "message": "example"
    }
  ]
}

413

Section titled “413”

The bounded Preview payload or inputs are too large.

Media typeapplication/json
object
error
required
string
code
string
draft_revision
string
issues
Array<object>
object
code
required
string
path
required
string
message
required
string
Examplegenerated
{
  "error": "example",
  "code": "example",
  "draft_revision": "example",
  "issues": [
    {
      "code": "example",
      "path": "example",
      "message": "example"
    }
  ]
}

502

Section titled “502”

Provider execution failed; the response remains sanitized.

Media typeapplication/json
object
success
required
boolean
source
string
Allowed values: single_agent_unsaved_preview
execution_id
required
string
result
object
key
additional properties
any
error
string
code
string
trace
required
object
status
required
string
Allowed values: succeeded failed
duration_ms
required
integer
provider
required
string
model
required
string
interaction_mode
required
string
Allowed values: completion chat
http_status
integer
>= 100 <= 599
Example
{
  "source": "single_agent_unsaved_preview",
  "trace": {
    "status": "succeeded",
    "interaction_mode": "completion"
  }
}

503

Section titled “503”

The referenced credential or Preview runtime is unavailable.

Media typeapplication/json
object
success
required
boolean
source
string
Allowed values: single_agent_unsaved_preview
execution_id
required
string
result
object
key
additional properties
any
error
string
code
string
trace
required
object
status
required
string
Allowed values: succeeded failed
duration_ms
required
integer
provider
required
string
model
required
string
interaction_mode
required
string
Allowed values: completion chat
http_status
integer
>= 100 <= 599
Example
{
  "source": "single_agent_unsaved_preview",
  "trace": {
    "status": "succeeded",
    "interaction_mode": "completion"
  }
}