Real-time Functions

run_function(
    name: str,
    input_data: dict | str | BaseModel,
    langsmith_metadata: dict[str, Any] | None = None,
    langsmith_tags: list[str] | None = None,
    timeout_seconds: float | None = None,
) -> FunctionRunResult

Parameter	Description
`name`	Published Function name. Do not include a namespace or revision.
`input_data`	The Function’s input fields. Keys must match the Function inputs; every field is required and unknown fields are rejected. A bare string is accepted when the Function has exactly one text input. Image and PDF fields take an `Asset` or `Image` value.
`langsmith_metadata`, `langsmith_tags`	Optional trace metadata when `LANGSMITH_TRACING=true`.
`timeout_seconds`	How long to wait for the answer. Defaults to just above the deployment’s standard 90 s request deadline; raise it for a deployment whose deadline was raised.

import sutro as so

result = so.run_function(
    "support-escalation",
    {"text": "The customer reports an unrecognized charge."},
)

label = result.output["label"]
if result.confidence <= 0.6:
    # Low confidence: log the request ID so someone can check this one by hand.
    print(f"check request {result.request_id}: {label} at {result.confidence:.2f}")

Use batch_run_function() instead for large tables; run_function() makes one synchronous request per call and can be rate limited. See Run a Function for the full request and response contract, limits, and error codes.

FunctionRunResult

The return value is a dict of the response payload, with its fields also available as attributes.

Attribute	Description
`output`	The answer, parsed against the Function’s output schema. A string when the Function has no schema.
`confidence`	The confidence score for this answer, between 0 and 1.
`usage`	`input_tokens`, `output_tokens`, and `cost_usd` for the request.
`request_id`	The deployment’s ID for this request, for log and support lookups.
`function`	The Function’s `name`, `model`, and `model_source` (`model-sweep` or `sutro-default`).

Assets

Image and PDF input fields take a value built by sutro.Image or sutro.Asset. Both return plain dicts, so they can also be written out by hand or serialized with json.dumps().

Constructor	Value
`Image.from_path(path)`	Reads the file and infers its type from the extension.
`Image.from_bytes(data, mime_type, filename=None)`	Inline bytes with an explicit MIME type.
`Image.from_url(url)`	An `https://` URL the deployment downloads.
`Asset.from_path(path)`, `Asset.from_bytes(...)`, `Asset.from_url(...)`	The same, also accepting PDFs.
`Asset.from_name(name)`	An asset already stored in the deployment.

import sutro as so

so.run_function(
    "invoice-reader",
    {
        "scan": so.Asset.from_path("invoices/april.pdf"),
        "logo": so.Image.from_url("https://cdn.example.com/logo.png"),
    },
)

Image accepts image/png, image/jpeg, and image/webp; Asset also accepts application/pdf. Anything else raises ValueError before the request is sent.

Errors

run_function() never retries. Every failure raises a requests.HTTPError subclass carrying the deployment’s detail, code, and request_id.

Exception	Raised for
`sutro.SutroRateLimitError`	`429`. `retry_after` is the number of seconds to wait, from the `Retry-After` header, or `None` when the deployment sent none.
`sutro.SutroValidationError`	`422`. The input does not match the Function, an asset could not be read, or the Function cannot run in real time on its current model.
`requests.HTTPError`	Every other API failure, including `404`, `409`, `502`, `503`, and `504`.

import time
import sutro as so

try:
    result = so.run_function("support-escalation", {"text": text})
except so.SutroRateLimitError as error:
    time.sleep(error.retry_after or 1)
    result = so.run_function("support-escalation", {"text": text})
except so.SutroValidationError as error:
    print(error.detail, error.code)
    raise

Command line

sutro functions run support-escalation --input '{"text": "..."}'
sutro functions run support-escalation --input @request.json

--input takes a JSON object, or @ followed by the path to a file holding one. The command prints the JSON response and exits non-zero with the deployment’s detail on failure.

Product

MCP

Python SDK

API

Real-time Functions

Real-time Functions

FunctionRunResult

Assets

Errors

Command line

​Real-time Functions

​FunctionRunResult

​Assets

​Errors

​Command line

Real-time Functions

FunctionRunResult

Assets

Errors

Command line