---
title: "agent.ui-event@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/agent.ui-event"
updated: null
---

# agent.ui-event@1 · OpenVibe.Services

HTML: [agent.ui-event@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/agent.ui-event)

# AgentUiEvent `agent.ui-event@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: actor
- Visibility: public
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/agent/ui-event.v1.json`](/docs/contracts/agent.ui-event.json)

agent.ui-event@1: AG-UI 1.0 event shape and event-family fields, with OpenVibe metadata.ov. AG-UI timestamps are Unix-millisecond integers; this contract requires one on every event. CUSTOM events use AG-UI name/value with ov.sources, ov.handoff, ov.approval or ov.result names.

## Fields

This schema has no named fields.

## Examples

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

 Valid: activity

~~~~
{
  "type": "ACTIVITY_SNAPSHOT",
  "timestamp": 1794355200000,
  "messageId": "activity_1",
  "activityType": "plan",
  "content": {
    "step": "read"
  },
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: custom

~~~~
{
  "type": "CUSTOM",
  "timestamp": 1794355200000,
  "name": "ov.sources",
  "value": [
    {
      "url": "https://example.com",
      "title": "Example",
      "site": "example.com"
    }
  ],
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: example

~~~~
{
  "type": "STEP_STARTED",
  "timestamp": 1794355200000,
  "metadata": {
    "ov": {
      "title": "Searching the web",
      "kind": "search",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  },
  "stepName": "Research"
}
~~~~

Valid: passthrough

~~~~
{
  "type": "RAW",
  "timestamp": 1794355200000,
  "event": {
    "provider": "native"
  },
  "source": "codes",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: reasoning

~~~~
{
  "type": "REASONING_START",
  "timestamp": 1794355200000,
  "messageId": "reason_1",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: run

~~~~
{
  "type": "RUN_STARTED",
  "timestamp": 1794355200000,
  "threadId": "thread_1",
  "runId": "run_1",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ],
      "needs_you": {
        "id": "approval_1",
        "question": "May I publish the result?",
        "actions": [
          "approve",
          "decline"
        ]
      }
    }
  }
}
~~~~

Valid: state

~~~~
{
  "type": "STATE_SNAPSHOT",
  "timestamp": 1794355200000,
  "snapshot": {
    "plan": []
  },
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: steps

~~~~
{
  "type": "STEP_STARTED",
  "timestamp": 1794355200000,
  "stepName": "Read repositories",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: subagents

~~~~
{
  "type": "SUBAGENT_STARTED",
  "timestamp": 1794355200000,
  "subagentRunId": "sub_1",
  "name": "Research",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: text

~~~~
{
  "type": "TEXT_MESSAGE_CONTENT",
  "timestamp": 1794355200000,
  "messageId": "msg_1",
  "delta": "Reading source",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Valid: tools

~~~~
{
  "type": "TOOL_CALL_START",
  "timestamp": 1794355200000,
  "toolCallId": "call_1",
  "toolCallName": "read_file",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: activity

~~~~
{
  "type": "ACTIVITY_SNAPSHOT",
  "timestamp": 1794355200000,
  "activityType": "plan",
  "content": {
    "step": "read"
  },
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: custom

~~~~
{
  "type": "CUSTOM",
  "timestamp": 1794355200000,
  "name": "ov.sources",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: example

~~~~
{
  "type": "NOT_AN_AGUI_EVENT",
  "timestamp": "not-an-epoch"
}
~~~~

Rejected: passthrough

~~~~
{
  "type": "RAW",
  "timestamp": 1794355200000,
  "source": "codes",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: reasoning

~~~~
{
  "type": "REASONING_START",
  "timestamp": 1794355200000,
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: run

~~~~
{
  "type": "RUN_STARTED",
  "timestamp": 1794355200000,
  "threadId": "thread_1",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: state

~~~~
{
  "type": "STATE_SNAPSHOT",
  "timestamp": 1794355200000,
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: steps

~~~~
{
  "type": "STEP_STARTED",
  "timestamp": 1794355200000,
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: subagents

~~~~
{
  "type": "SUBAGENT_STARTED",
  "timestamp": 1794355200000,
  "subagentRunId": "sub_1",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: text

~~~~
{
  "type": "TEXT_MESSAGE_CONTENT",
  "timestamp": 1794355200000,
  "delta": "Reading source",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

Rejected: tools

~~~~
{
  "type": "TOOL_CALL_START",
  "timestamp": 1794355200000,
  "toolCallName": "read_file",
  "metadata": {
    "ov": {
      "title": "Researching the question",
      "kind": "read",
      "product": "codes",
      "sources": [
        {
          "url": "https://example.com",
          "title": "Example",
          "site": "example.com"
        }
      ]
    }
  }
}
~~~~

## Validate

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