Skip to main content
Hand the design of a compensation to the Architect, Qobra’s compensation design agent. Each call runs one turn of a conversation in which the Architect builds, changes or explains a compensation’s calculation: scopes, fields, formulas, tiers, accelerators and payout. Use it when the user wants a compensation built or changed from a description in their own words (“pay 5% of every closed deal”), or wants to understand why a compensation computes what it does (“why is Q3 at zero?”).

​
Start and continue a conversation

Start a conversation with an instruction and the compensation_id to work on. get_plan lists a plan’s compensations, and create_compensation opens an empty one. Every later call of the same work passes back the conversation_id the first call returned, a retry included. Without it, Qobra starts a new conversation and the Architect loses what was said. The conversation also shows on the compensation in the Qobra web app.

​
Read the result

status says where the turn stands:
  • answered: the Architect finished its turn. Relay answer to the user.
  • awaiting_user: the Architect paused on a question (pending_question) or on a plan of changes to validate (pending_plan). The client must show it to the user as it is, wait for their reply, and send that reply as the next instruction with the same conversation_id. Approving a plan is the user’s decision, not the model’s.
  • running: the turn is still going. Each call waits about 45 seconds before answering running, and a turn can take several minutes. Call get_architect_turn with the conversation_id to keep waiting. Calling ask_architect on a conversation whose turn is still running is refused.
A turn that ends on an error is raised as a tool error that names the conversation, so the client can send the instruction again in it.

​
Draft only, never published

What the Architect changes is saved as the compensation’s draft. Nothing reaches a statement until the user publishes the draft in the Qobra web app. Each turn starts from the latest draft, including one edited in the app meanwhile. The result carries the compensation to review, in the same shape get_plan lists it. saved is true when the turn’s changes were saved as the draft. It is false when nothing was saved, and save_note says why.

​
Availability

Available only where the Qobra write tools beta is enabled and the Architect is switched on for the company. The caller needs write access on plan compensations, as in the web app.

​
Parameters

Body

​
string
required
What to ask or tell the Architect, in the user’s words: ‘pay 5% of every closed deal’, ‘why is Q3 at zero?’. Also the user’s answer to a question or a plan it is waiting on.
​
string
Id of the compensation to work on: the id get_plan lists, or the one create_compensation returns. Needed to start a conversation; a conversation_id already names its compensation.
​
string
Id of the conversation to continue: the one an earlier ask_architect call returned. Omit it only to start a new conversation on a compensation.

​
Response

Body

​
string
‘answered’: the Architect finished its turn, its reply is in answer. ‘awaiting_user’: it paused on a question (pending_question) or on a plan to validate (pending_plan); show it to the user and send their reply as the next instruction of this conversation with ask_architect. ‘running’: a turn is still going; call get_architect_turn with this conversation_id to keep waiting for it. One of: answered, awaiting_user, running.
​
string
The conversation this turn belongs to, the same one the web app shows on the compensation. Pass it back on every follow-up call.
​
string
The Architect’s reply when status is ‘answered’, to relay to the user. Null otherwise.
​
object
The question the Architect is waiting on, with the options it offers (multi_select: several may be picked; the user may also answer in their own words). Set only when status is ‘awaiting_user’.
​
object
The changes the Architect proposes, waiting for the user to approve or amend them; it applies nothing before. Set only when status is ‘awaiting_user’.
​
object
The compensation to review, as get_plan lists it: its draft version when it has one, the compensation itself otherwise. Publishing it is the user’s decision, made in the Qobra web app.
​
boolean
True: the turn’s changes were saved as the compensation’s draft, which nothing reads until the user publishes it. False: nothing was saved, save_note says why. Null while a turn runs, and for a turn asked from the web app, which saves from its own page.
​
string
Why nothing was saved, or what the save had to change on the way, to tell the user. Null when there is nothing to add.