Beta. The assistant API and its reads over MCP are in beta. They are open to every
organization that pays out through Grade, and parts are not available yet, as each page says.
POST to the assistant’s URL, which ends in /v2/api/agent. Grade keeps no
conversation for you: every request carries the history and the open proposals again.
Headers
Request body
JSON, at most 32 KB in UTF-8. A field this page does not name is refused with400.
History is text only. An
assistant message holds an answer’s text deltas, joined. Proposals never
go in messages: they go back as app events.
App events
Both kinds carry"type": "app_event" and the time in at.
open_proposalgoes with every question for the latest proposal of each action, until a newer one arrives, so the person can correct it in words (“add Maya too”). It carries the proposal’saction_idandaction, itsstatus(open, orappliedonce a row saved) and thedrafttheactionevent gave. Only a proposal with adraft, which comes with thecardformat, has one.actiongoes once, with what became of a proposal:
The optional
counts holds whole numbers: added for saved rows, failed for refused and
not_sent, and unconfirmed for unknown, leaving out zeros.
Events
The answer istext/event-stream: each frame is an event: line and a data: line with one JSON
object. A frame starting with : (: keep-alive, every 15 seconds while the model thinks) is a
comment: skip it. The x-agent-run-id response header carries the run’s id, on refusals too: log it
and quote it when you contact Grade.
run_started comes first and turn_completed last, with any number of step_started, step, text
and action between them. A stream that closes without turn_completed, or sends error instead,
failed: treat it as stream_error.
The answer’s text is a small Markdown subset (paragraphs, headings, lists, small tables, bold and
inline code) with no links or images. Draw it with a renderer that escapes HTML, or as plain text: it
is model-written, and it quotes data from people outside your team.
A proposal
An
action event without a proposal_token has nothing to commit: show no confirm button. When a
newer proposal of the same action arrives, turn the older one’s button off. When a proposal can’t be
sent, no action event comes: its step ends with PROPOSAL_TOO_LONG or PROPOSAL_UNAVAILABLE, and
the assistant says so in words.
Every event and its fields
run_started
step_started
step
text
view_delta
view
view_rejected
action
turn_completed
error
Refusals before the stream
A refused question answers JSON,{ "code": "..." }, and no stream.
How an answer ended
turn_completed.run_outcome says how an accepted question ended, and error_class why, in one word.
Try again resends the same request.
Compatibility
Events and fields are only ever added: ignore an event or a field you don’t know, and read a newrun_outcome or error_class as a failure. A change you would have to adapt to comes as a new
api_version, which you ask for. The request is the other way round: Grade refuses what it doesn’t
know.