Give the model facts and a rule
The state field contains context shared by the questions. It can include a message and the rules for making a decision. The questions field defines named questions; their identifiers connect the answers to your application's logic.
Use stable keys for Choice options, such as engineering, finance and logistics. The description explains the option, while the key remains part of your integration contract. Changing a key requires a corresponding change in the code that handles the result.
{
"state": "A customer reports that the payment page shows an error. Rule: route website failures to engineering, questions about charged payments to finance, and delivery issues to logistics.",
"questions": {
"team": {
"type": "choice",
"instructions": "Which team should handle this request under the given rule?",
"criteria": {
"engineering": "Website or integration failure",
"finance": "Charged payments and invoices",
"logistics": "Shipping and delivery"
}
}
}
}Separate the request from the external action
Send JSON with POST /v1/systemone and your API key in the Authorization: Bearer header. Keep the service address and key in server-side environment variables. The documentation examples show an HTTP call; a specific SDK is not required for your first integration.
Receiving a response does not mean the ticket has been routed. First check the HTTP status and data structure, then confirm that the required question has an answer. Only then apply your routing rule. If the call fails, leave the ticket in a queue where it can still be handled.
Make your integration observable
Associate each call with your internal ticket ID, rule version and selected action. This lets you investigate an error without confusing a network failure with an incorrect model decision. If you store texts in your own system, define in advance how much to retain and who can access them.
Start without changing routes automatically: compare the API's suggestion with an agent's decision. Once you understand common errors, define rules for automation and human review. Repeating an HTTP call and repeating an external action are different events; protect your application against duplicating the latter.