agentops-rpc

Shared Pydantic wire types for the AgentOps SDK and controlplane.

Both the SDK (komodor-agentops) and the controlplane import models from this package, giving build-time (mypy) and runtime (Pydantic v2) type safety across the wire boundary.

Install

pip install agentops-rpc

Quick Start

from agentops_rpc import RunEventIn, IngestRunEventsRequest, HOOK_EVENT_TYPE_MAP

event = RunEventIn(
    event_type="span.started",
    span_id="span_abc",
    kind="tool",
    name="Bash",
    hook_event_type="tool.start",
)
event.model_dump()  # JSON-safe dict

request = IngestRunEventsRequest(worker_id="wrk_1", events=[event])

Exported Models

types.py -- Literal type aliases

Type	Values
`EventType`	`run.started`, `run.completed`, `run.failed`, `span.started`, `span.ended`, `message.created`, `log.created`, `token.created`, `custom.created`, `output.updated`
`RunStatus`	`queued`, `claimed`, `running`, `succeeded`, `failed`
`SpanKind`	`agent`, `llm`, `tool`, `chain`, `generation`
`HookEventName`	`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `SubagentStart`, `SubagentStop`, `Notification`, `Stop`, `SessionEnd`, `PermissionRequest`, `PreCompact`, `PostCompact`
`HookEventType`	`session.start`, `prompt.submit`, `tool.start`, `tool.end`, `tool.error`, `subagent.start`, `subagent.end`, `notification`, `session.stop`, `compaction.start`, `compaction.end`
`AgentStatus`	`online`, `offline`
`RunTransport`	`polling`, `api_sync`, `api_sse`, `a2a`

events.py -- Event ingest models

RunEventIn -- unified event sent SDK -> controlplane
TraceEventIn, LogEventIn -- structured events for DB tables
IngestRunEventsRequest / IngestRunEventsResponse
BatchEventsRequest
TraceEventResponse, LogEventResponse, RunMessageResponse

runs.py -- Run lifecycle models

CreateRunRequest, RunSummary, RunDetail, RunJob
PollNextRunRequest, ClaimRunResponse
StartRunRequest, StartRunDirectRequest
CompleteRunRequest, FailRunRequest, UpdateRunOutputRequest
InvokeAgentRequest / InvokeAgentResponse
WorkerInvokeRequest / WorkerInvokeResponse

agents.py -- Agent registration models

AgentManifest, HeartbeatRequest, HeartbeatResponse
AgentInstanceResponse

hook_types.py -- Hook event mapping

HOOK_EVENT_TYPE_MAP -- maps Claude Code HookEventName to HookEventType

a2a.py -- A2A protocol wire types

A2AMessage, A2AMessagePart
A2AMessageRequest, A2ATaskResponse

Type Safety Guarantees

Layer	Protection
Build-time (mypy)	SDK and controlplane import the same Pydantic models -- field mismatches caught at type-check
Runtime (Pydantic)	Every event validated at construction and at API boundary
Wire (JSON)	`model_dump()` / `model_validate()` guarantee JSON matches schema
Hook events	`HookEventType` literal -- typos fail both type-check and runtime

Adding a CP↔worker frame type

Four steps, none of them a Python edit. schemas/frames.schema.json is the hand-authored source of truth; Python, Go and TypeScript are all generated from it, and no language is privileged.

Add the payload to $defs, and bind it in x-agentops-frames ("my_frame": "MyFramePayload"). Leave additionalProperties out rather than setting it true — the schema's own description explains why the two differ in generated Go.
Declare how it travels in x-agentops-delivery — control (send now or fail now) or at-least-once (buffered, retried, may deliver twice, ordered per stream). There is no default and the generator refuses to run without one, because either default is wrong for half the types.
Add a fixture under schemas/fixtures/ (and fixtures/invalid/ if the type has a constraint worth proving). A per-type coverage guard fails without one.
Run make generate-frames. This writes the Python models and registry, the Go wire types, and the TypeScript bindings together — plus the MY_FRAME constant and the package's __all__, so from agentops_rpc.wire import MY_FRAME, MyFramePayload works with no further edit. make check-frames is the CI guard that the committed artifacts match the schema.

The one thing that does still cost a Python line is a payload with an inline sub-schema: the registry binds top-level payload schemas, so a shape nested inside one is invisible to the generator and each language names it differently. wire/__init__.py aliases it once (see Event as RunEvent). A payload built only from $defs and scalars needs nothing.

Everything after that is feature code: a Router.on(MY_FRAME) handler on the worker side, a caller on the control-plane side. See docs/reference/cp-worker-protocol.md for how frames reach a worker and how a reply is correlated.

Dependencies

Only pydantic>=2.0. Zero internal dependencies.

Metadata

Release files for agentops-rpc 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentops-rpc 0.4.0
File	Size	Uploaded
agentops_rpc-0.4.0.tar.gz	171.2 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for agentops-rpc 0.4.0
File	Interpreter	ABI	Platform	Reset
agentops_rpc-0.4.0-py3-none-any.whl 168.2 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 339.4 kB

Release files / agentops_rpc-0.4.0.tar.gz

Download URL	agentops_rpc-0.4.0.tar.gz
Size	171.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`2f45f3824e1d6bac11d69f485bb180ff6cd4fa78dac34e6281d4f32bdf16585a`
BLAKE2b-256 checksum How to use checksums	`d6db9d7c538baecd20adb3afceca0885b111b95a30a3873315033c2ad5dc5266`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.13 {"installer":{"name":"uv","version":"0.11.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / agentops_rpc-0.4.0-py3-none-any.whl

Download URL	agentops_rpc-0.4.0-py3-none-any.whl
Size	168.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7d12d00d705fba03162dabd575c4d9bb0da9979973b1ff045fb15c899f5cb4fb`
BLAKE2b-256 checksum How to use checksums	`264078fa4d7d8aabaf246a0dce58dd8f894b75c51f20edfc1f6005bb5fe74720`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.13 {"installer":{"name":"uv","version":"0.11.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`