Inputs and outputs

A workflow has a contract with the code that calls it. Your code sends inputs. The workflow returns an outcome label and a result, along with execution metadata. Nothing else crosses the boundary. The graph behind the contract can change freely. The contract itself is what your integration depends on.

Declared inputs

A workflow declares the inputs it accepts. Each one has four parts.

Part	What it means
Name	The key your code sends, and the variable the instructions read.
Type schema	A JSON Schema fragment. It says whether the value is a string, a number, an array, or an object.
Required flag	Whether an execution can start without this value.
Default	The value used when an optional input is missing.

Your code sends the values in the inputs object on the execute call.

{
  "inputs": {
    "patientName": "Jane Doe",
    "dateOfBirth": "1984-02-11",
    "appointmentTypes": ["annual physical", "follow-up"]
  }
}

Rules

A name matches [a-zA-Z_][a-zA-Z0-9_]* and is unique within the workflow.
Values are validated against the declared schema when the execution starts.
A required input with no value fails the execution immediately. It does not fail halfway through.
An omitted optional input falls back to its default. With no default, it falls back to nothing.

The workflow’s deploy page lists the exact set of inputs, at https://platform.asteroid.ai/agents/<agent-id>/deploy. Read the names there rather than guessing them from the instructions.

Inputs reach the instructions as variables

An input named patient_name appears in the instructions as {{.patient_name}}.

Navigate to the patient search page:
Enter {{.patient_name}} into the search bar
Select the matching result
Fill {{.diagnosis}}
Click Submit

Nested JSON reads with a dot path, as {{.user.name}}. See Nodes.

Outcome labels

An outcome label answers one question: how did this execution finish? Every output node lists the labels it can produce. The label the execution lands on comes back to your code, and your code branches on it. The default pair is success and failure. Replace it with labels that name your real end states.

Kind of workflow	Labels worth declaring
Checkout	`purchase_completed`, `payment_failed`, `item_unavailable`, `session_expired`
Scheduling	`slots_found`, `no_slots_available`, `login_required`
Review	`approved`, `rejected`, `needs_review`

Rules

A label matches ^[a-z0-9_]{1,30}$. Lowercase letters, digits, and underscores only, 1 to 30 characters.
Spaces, hyphens, and capitals are rejected when you save the node.
Each output node declares at least 1 label and at most 20.
Labels are unique within a node.

Choosing labels

Name the end state, not the feeling. Write payment_completed, not done.
Declare every realistic end state, including the ones you would rather not meet.
Keep the same names across workflows that do similar work.
Test that an execution can actually reach each label.

Outcome labels are the contract. Treat a new label as a breaking change to your callers, and ship it as a new version.

Result schema

Alongside the label, an output node can return structured data. You define the shape as a JSON Schema, and the workflow fills it in. The format follows OpenAI Structured Outputs, a subset of JSON Schema.

{
  "type": "object",
  "properties": {
    "product_name": {
      "type": "string",
      "description": "The name of the product"
    },
    "price": {
      "type": "number",
      "description": "The product price"
    },
    "in_stock": {
      "type": "boolean",
      "description": "Whether the product is available"
    }
  },
  "additionalProperties": false,
  "required": ["product_name", "price", "in_stock"]
}

Rules

The root is an object with a properties map.
Every object type includes "additionalProperties": false.
List every property in the required array.
Use description on each property. The workflow reads it to decide what to put there.
oneOf, allOf and $ref are rejected. anyOf and enum are allowed.
The schema is at most 15,000 characters when serialized as JSON.

Check a schema with schemaValidate before you put it on an output node. See Build from your coding agent. Add a schema when downstream systems expect defined fields, or when the execution extracts several values. Start with labels alone, and add a schema once you know what you need back.

A result schema is not a transition schema.The output node’s schema defines the execution’s final result. A transition’s schema defines the payload handed to the next node, which reads it as {{.output}}. A transition payload never reaches your code.

What comes back

GET /executions/{executionId} returns the execution. The contract lives under executionResult.

Field	Type	Use it for
`outcome`	string	Branching. One of the workflow’s declared labels.
`result`	object	The data, matching the result schema.
`reasoning`	string	Logs and support tickets. Never branch on it.
`createdAt`	string	When the result was recorded.
`id`	string	The result’s own identifier.
`executionId`	string	The execution this result belongs to.

{
  "id": "0a19c3f6-2b41-4d0e-9f77-1c8a5d2e6b30",
  "status": "completed",
  "executionResult": {
    "outcome": "no_slots_available",
    "reasoning": "The portal returned an empty calendar for the requested week.",
    "result": { "slots": [], "nextAvailable": "2026-04-08" },
    "createdAt": "2026-03-27T11:04:12Z"
  },
  "duration": 148.2,
  "inputs": { "patientName": "Jane Doe" },
  "recordingUrl": "https://…",
  "platformUrl": "https://platform.asteroid.ai/agents/…/executions/…"
}

executionResult is absent when an execution ends before it reaches an output node. Check that it exists before you read it.

Branch on outcome, not on status

The status tells you the execution finished. The outcome tells you what happened. completed means the workflow reached an output node. It does not mean the work succeeded. An execution that correctly reports “this patient has no coverage” is completed. So is an execution that booked the appointment. The outcome label is what separates them.

import { client, executionGet } from 'asteroid-odyssey';

client.setConfig({
  baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
  headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});

const { data: execution, error } = await executionGet({
  path: { executionId: process.env.EXECUTION_ID! },
});
if (error) throw new Error(JSON.stringify(error));

const { outcome, result } = execution.executionResult ?? {};

switch (outcome) {
  case 'slots_found':
    await saveSlots(result);
    break;
  case 'no_slots_available':
    await scheduleRetry(result.nextAvailable);
    break;
  default:
    await escalate(execution.platformUrl, outcome);
}

import os

from asteroid_odyssey import ApiClient, Configuration
from asteroid_odyssey.api.execution_api import ExecutionApi

config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})

with ApiClient(config) as api_client:
    execution = ExecutionApi(api_client).execution_get(
        execution_id=os.environ["EXECUTION_ID"],
    )

result = execution.execution_result

if result is None:
    escalate(execution.platform_url, None)
elif result.outcome == "slots_found":
    save_slots(result.result)
elif result.outcome == "no_slots_available":
    schedule_retry(result.result["nextAvailable"])
else:
    escalate(execution.platform_url, result.outcome)

curl "https://odyssey.asteroid.ai/agents/v2/executions/$EXECUTION_ID" \
  -H "X-Asteroid-Agents-Api-Key: $ASTEROID_API_KEY" \
  | jq '.executionResult.outcome, .executionResult.result'

JSON and the TypeScript SDK use camelCase, as in executionResult. The Python SDK exposes the same field as execution.execution_result.

Call a workflow from your code

Send inputs, wait for the execution, read the result

Executions and statuses

Every status an execution passes through, and which ones are terminal

Nodes

Where labels and result schemas are configured

Versions and publishing

Ship a contract change without breaking callers

Start here

Build workflows

Integrate

Operate

Concepts

Healthcare workflow automation

SDKs

What's new

Support and security

Declared inputs

Rules

Inputs reach the instructions as variables

Outcome labels

Rules

Choosing labels

Result schema

Rules

What comes back

Branch on outcome, not on status

Call a workflow from your code

Executions and statuses

Nodes

Versions and publishing

​Declared inputs

​Rules

​Inputs reach the instructions as variables

​Outcome labels

​Rules

​Choosing labels

​Result schema

​Rules

​What comes back

​Branch on outcome, not on status

​Related

Call a workflow from your code

Executions and statuses

Nodes

Versions and publishing

Declared inputs

Rules

Inputs reach the instructions as variables

Outcome labels

Rules

Choosing labels

Result schema

Rules

What comes back

Branch on outcome, not on status

Related