---
title: "agents.message@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/agents.message"
updated: null
---

# agents.message@1 · OpenVibe.Services

HTML: [agents.message@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/agents.message)

# AgentsMessage `agents.message@1`

Generated at 2026-11-17 06:52:56 UTC from [`openvibe-contracts v0.443.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.443.0) and [`openvibe-sdk v0.177.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.177.0).

- Version: 1.0.0
- Owner: network
- Visibility: public
- Status: active
- Compatibility: backward
- Decision: [ADR-044](/docs/adr/ADR-044)
- Schema: [`https://openvibe.network/contracts/agents/message.v1.json`](/docs/contracts/agents.message.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 |  | - `minLength 1`<br>- `maxLength 100000` |
| `attachments` | array of object |  |  | - `maxItems 20`<br>- `items: no other fields` |
| `attachments[].kind` | enum | yes |  | - `one of "image", "file", "audio", "video"` |
| `attachments[].media_id` | string |  |  | - `minLength 1`<br>- `maxLength 60` |
| `attachments[].url` | string |  | An https address the reader may fetch. | - `format uri`<br>- `maxLength 2000` |
| `attachments[].name` | string |  |  | - `maxLength 300` |
| `attachments[].mime` | string |  |  | - `maxLength 120` |
| `attachments[].bytes` | integer |  |  | - `minimum 0` |
| `attachments[].width` | integer |  |  | - `minimum 1` |
| `attachments[].height` | integer |  |  | - `minimum 1` |
| `attachments[].alt` | string |  | What a picture shows, in words. | - `maxLength 500` |
| `use` | object |  | What runs from this turn on. Absent: the run keeps what it had. | - `no other fields` |
| `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. | - `no other fields` |
| `use.model.id` | string | yes |  | - `pattern ^[A-Za-z0-9._:/@+\| -]+$`<br>- `minLength 1`<br>- `maxLength 200` |
| `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. | - `one of "openvibe", "keys", "machines", "plans"` |
| `use.model.machine` | string |  |  | - `maxLength 40` |
| `use.model.name` | string |  |  | - `minLength 1`<br>- `maxLength 200` |
| `use.model.effort` | string |  |  | - `minLength 1`<br>- `maxLength 40` |
| `use.harness` | string |  | A 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.effort` | enum |  |  | - `one of "low", "medium", "high", "max"` |
| `idempotency_key` | string |  |  | - `pattern ^[A-Za-z0-9._:-]+$`<br>- `minLength 8`<br>- `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 }] }
~~~~
