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
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
text | string | yes |
| |
attachments | array of object |
| ||
attachments[].kind | enum | yes |
| |
attachments[].media_id | string |
| ||
attachments[].url | string | An https address the reader may fetch. |
| |
attachments[].name | string |
| ||
attachments[].mime | string |
| ||
attachments[].bytes | integer |
| ||
attachments[].width | integer |
| ||
attachments[].height | integer |
| ||
attachments[].alt | string | What a picture shows, in words. |
| |
use | object | What runs from this turn on. Absent: the run keeps what it had. |
| |
use.model | object | The 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. |
| |
use.model.id | string | yes |
| |
use.model.source | enum | openvibe: 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. |
| |
use.model.machine | string |
| ||
use.model.name | string |
| ||
use.model.effort | string |
| ||
use.harness | string | A coding harness by its id (claude-code, codex, opencode, openvibe, …): a code run hands its thread to it. |
| |
use.effort | enum |
| ||
idempotency_key | string |
|
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 }] }