AgentsMessage agents.message@1

Generated at from openvibe-contracts v0.443.0 and openvibe-sdk v0.177.0.

Version
1.0.0
Owner
network
Visibility
public
Status
active
Compatibility
backward
Decision
ADR-044
Schema
https://openvibe.network/contracts/agents/message.v1.json

agents.message@1 (0.434.0; the owner, 2026-11-14: "resume sessions or swap models with ease"): the body of POST /runs/{id}/messages on every product's Run API and the Frame (openvibe-sdk/agents/api), answered 201 with the agents.step@1 it made. TEXT is the person's words for the run's next turn. USE swaps what runs that turn and every turn after it, in the same run and the same thread: another MODEL (agents.run@1's model shape, any of Exchange's or the person's own), another HARNESS (a coding harness by its id, for a code run), another EFFORT. The thread carries over whole, so nothing is restated; a product that cannot run the asked model or harness answers 409 agents.use_unavailable and changes nothing. A run that had ended takes the message as a resume: it runs again from its last step (status running), unless its product refuses with 409 agents.run_closed. Starting a new run that continues this one elsewhere is agents.run-start@1 with LINEAGE (fork, handoff, regenerate).

Fields

FieldTypeRequiredDescriptionConstraints
textstringyes
  • minLength 1
  • maxLength 100000
attachmentsarray of object
  • maxItems 20
  • items: no other fields
attachments[].kindenumyes
  • one of "image", "file", "audio", "video"
attachments[].media_idstring
  • minLength 1
  • maxLength 60
attachments[].urlstringAn https address the reader may fetch.
  • format uri
  • maxLength 2000
attachments[].namestring
  • maxLength 300
attachments[].mimestring
  • maxLength 120
attachments[].bytesinteger
  • minimum 0
attachments[].widthinteger
  • minimum 1
attachments[].heightinteger
  • minimum 1
attachments[].altstringWhat a picture shows, in words.
  • maxLength 500
useobjectWhat runs from this turn on. Absent: the run keeps what it had.
  • no other fields
use.modelobjectThe model that runs it, as the picker chose it (frame.choices@1's choice, with the name a person reads). EFFORT is the reasoning effort where the model has one.
  • no other fields
use.model.idstringyes
  • pattern ^[A-Za-z0-9._:/@+| -]+$
  • minLength 1
  • maxLength 200
use.model.sourceenumopenvibe: Exchange's directory, paid in credits. keys: the person's own key. machines: a model on the person's own computer (Link). plans: a signed-in plan through a harness.
  • one of "openvibe", "keys", "machines", "plans"
use.model.machinestring
  • maxLength 40
use.model.namestring
  • minLength 1
  • maxLength 200
use.model.effortstring
  • minLength 1
  • maxLength 40
use.harnessstringA coding harness by its id (claude-code, codex, opencode, openvibe, …): a code run hands its thread to it.
  • pattern ^[a-z0-9][a-z0-9-]{0,39}$
use.effortenum
  • one of "low", "medium", "high", "max"
idempotency_keystring
  • pattern ^[A-Za-z0-9._:-]+$
  • minLength 8
  • maxLength 200

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: hand-to-codex
{
  "text": "Hand this to Codex",
  "use": {
    "harness": "codex",
    "effort": "high"
  },
  "idempotency_key": "msg-0001-abcdef"
}
Valid: plain
{
  "text": "Keep going"
}
Valid: swap-model
{
  "text": "Now with a cheaper model",
  "use": {
    "model": {
      "id": "deepseek/deepseek-v4.1-flash",
      "source": "openvibe"
    }
  }
}
Rejected: bad-harness
{
  "text": "x",
  "use": {
    "harness": "Codex CLI!"
  }
}
Rejected: empty-use
{
  "text": "x",
  "use": {}
}
Rejected: no-text
{
  "use": {
    "harness": "codex"
  }
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('agents.message@1', value);   // { valid, errors: [{ path, message }] }