AgentsRunStart agents.run-start@1

Generated at 2026-11-13 06:25:48 UTC from openvibe-contracts v0.419.0 and openvibe-sdk v0.161.0.

Version

1.2.0

Owner

network

Visibility

public

Status

active

Compatibility

backward

Decision

ADR-044

Schema

https://openvibe.network/contracts/agents/run-start.v1.json

agents.run-start@1 (agent-engine.md, 2026-11-12): what starts a run, the same on every product's POST /api/v1/runs and on the Frame's POST /api/frame/runs. Only TEXT is required: the goal, the question or the first message, in the person's own words. KIND chooses the sort of run (agents.run@1's kinds); absent, the Frame's orchestrator decides whether to answer, plan, or hand the work to another product as a child run. AGENT names who does it (an agent's id; auto lets the product choose). MODEL and WHERE are the picker's choices; TARGET is a code run's (new, openvibe or a repository); CONTEXT is where it was asked; ATTACHMENTS are files by Media id or address; SOURCES and DEPTH are an answer's (frame.ask@1's); PARENT_RUN makes it a sub-agent's run inside its parent's budget; BUDGET is its own hard limit. An Idempotency-Key header makes a repeated start return the first run. Since 1.1.0 a start may name a PLAY, continue another run (LINEAGE), and carry intake's MANDATE.

Fields

Examples

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

{
  "text": "Add a goal bar overlay streamers can put on their stream, with the sub goal and progress.",
  "kind": "code",
  "target": "openvibe",
  "model": {
    "id": "openvibe/auto",
    "source": "openvibe"
  },
  "where": {
    "kind": "openvibe"
  },
  "context": {
    "site": "live",
    "url": "https://openvibe.live/dashboard",
    "title": "Dashboard"
  },
  "attachments": [
    {
      "kind": "image",
      "media_id": "med_01K9R2V6M8Q4T0B7C3D5E9F2GH",
      "alt": "A sketch of the bar"
    }
  ],
  "budget": {
    "usd": 5,
    "steps": 400
  }
}

{
  "text": "Same idea, but for a phone screen",
  "lineage": {
    "from": "chat:c_8f3k2m",
    "at_turn": 3,
    "how": "fork"
  }
}

{
  "text": "What happened in tech news today?",
  "kind": "ask",
  "sources": [
    "web",
    "openvibe"
  ],
  "depth": "balanced"
}

{
  "text": "A goal bar for my sub goal"
}

{
  "text": "Find the best moments from tonight",
  "blueprint": "bp_01JD8C4QJ7Z3K9W2X5V6N1M0PA@3"
}

{
  "text": "Write the patch notes for 4.225.0 and have them checked",
  "kind": "task",
  "play": "grader-loop"
}

{
  "text": "Find the best moments",
  "blueprint": "bp_01JD8C4QJ7Z3K9W2X5V6N1M0PA"
}

{
  "text": "Do it",
  "play": "Grader Loop!"
}

{
  "text": "fix it",
  "kind": "code",
  "target": "everything"
}

{
  "kind": "chat"
}

Validate

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