Agent Instructions

# Agent Status Reporting Instructions

## Overview

This document is intended for development-focused AI agents such as Cursor, Codex, and Claude Code.

Always send small item state-change logs to the bunny.fyi ingestion API while monitoring this service, system, pipeline, job, or automation.

Reporting mode: System Status

Use this mode when you are reporting the state of services, pipelines, deployments, crawlers, or jobs as readable item timelines.

## Important rules

- Never send the example payload unchanged.
- Always replace example values with real values from the current monitored system, service, pipeline, job, or automation.
- Do not send a status update just to confirm that you read these instructions.
- Generate a fresh current ISO timestamp for every update.
- Reuse the same `itemId` for the same item over time.
- Include a short `itemName` that a human can read quickly.
- Fill every required field on every request: `projectId`, `itemId`, `itemName`, `status`, `agentId`, and `event`.
- `status` is a restricted enum. Only use: `running`, `completed`, `failed`, `blocked`, `retrying`, `skipped`.
- Do not send any other `status` values. `unknown`, `updated`, `processed`, `healthy`, and `warning` are invalid.
- `event` must be one short human-readable line explaining why the current `status` is true or what just changed.
- Do not use generic `event` values like `updated`, `processed`, `completed`, `done`, or `ok`.
- Put the key outcome in `status` or `event`, not only in `detail`.
- Keep one payload focused on one item only.
- Use `detail` only for raw values, machine context, metrics, or debugging data.
- Do not hide the main result, outcome, or decision in `detail`.
- Choose identifiers carefully:
  - `projectId`: the real current product, system, or environment name
  - `agentId`: the actual agent you are running as, such as `cursor`, `codex`, or `claude_code`
  - `itemId`: the stable machine identifier for one monitored item
  - `itemName`: the human-readable name for that monitored item

## Field meaning

- `itemId`: stable machine id for one item
- `itemName`: human-readable item label
- `status`: one of `running`, `completed`, `failed`, `blocked`, `retrying`, `skipped`
- `event`: one short line explaining the current status or latest change
- `detail`: optional raw values, machine context, metrics, or debugging data

## When to send updates

Send an update:
- periodically while the system is being monitored, for example every few minutes
- when the monitored system enters a new health state
- when key metrics materially change
- immediately when warnings or failures appear
- when a degraded or failed system returns to healthy status

## API endpoint

https://www.bunny.fyi/api/records

## Authentication

Use this API key:

test_agent_key_local_123

Send the key in either of these ways:
- Authorization: Bearer test_agent_key_local_123
- x-api-key: test_agent_key_local_123

## Payload example

Send POST requests with JSON payloads similar to the example below.
Only `detail` and `timestamp` may be omitted.

{
  "projectId": "<current-product-or-environment-name>",
  "itemId": "<current-service-or-job-id>",
  "itemName": "<human-readable service or job name>",
  "status": "completed",
  "agentId": "<current-agent-name>",
  "event": "Marked run as completed after flat book",
  "timestamp": "2026-03-23T05:05:00.000Z",
  "detail": {
    "bookState": "flat",
    "positionsClosed": 3,
    "durationMs": 842
  }
}

## Good vs bad examples

Bad:
- `status`: "unknown"
- `event`: "updated"
- `status`: "healthy"
- `status`: "Processed 24 records successfully"
- `event`: "completed"

Good:
- `status`: "retrying"
- `event`: "Retrying broker sync after timeout"
- `status`: "failed"
- `event`: "Order execution failed due to timeout"
- `status`: "skipped"
- `event`: "No execution opened because check returned non-go"

## Recommended status values

- running for active work that is still in progress
- completed for a finished successful run
- failed for incidents, outages, or hard failures
- blocked for waiting on an external issue
- retrying for another attempt after a failure
- skipped for an intentional no-op

## Guidelines

- Keep every update short and clear.
- Write updates so a human can understand progress quickly from the dashboard.
- Prefer many small item updates over fewer large updates.
- Keep the human-readable meaning split across `itemName`, `status`, and `event`.
- Keep verbose machine data in `detail`.
- If raw data already contains the outcome, promote it into `status` or `event` instead of leaving it hidden in `detail`.
- Prefer meaningful milestone updates over noisy low-value chatter.