Agents and runs: identity and execution records

Register each agent you deploy with a durable identity, then record every execution as a run that moves from running to succeeded, failed, or cancelled exactly once.

Agents

An agent is an identity: a name, an optional description, and an optional external_id you already use. Flowyn stores no code, prompts, or model policy for it. Optional rolling-24h warning thresholds are advisory configuration.

curl -X POST https://api.flowyn.dev/v1/agents \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: register-refund-agent" \
  -d '{
    "name": "refund-agent",
    "description": "Handles refund requests from support tickets.",
    "external_id": "refund-agent"
  }'

Call	Effect
`POST /v1/agents`	Register. Returns 201.
`GET /v1/agents`	List, filter by `q`, `external_id`, or `archived`.
`PATCH /v1/agents/{id}`	Update metadata or warning thresholds. Send `expected_revision` and `Idempotency-Key`.
`POST /v1/agents/{id}/archive`	Archive. The id stays for attribution.
`POST /v1/agents/{id}/restore`	Restore if fewer than 100 agents are active.

Names are unique among active agents in an environment; an external_id is unique among all of them.
Up to 100 active agents per environment. Archived agents do not count.
Changes use expected_revision, so two editors cannot overwrite each other (409 agent_revision_conflict).

Runs

A run records one execution your runtime performs. Flowyn does not run, queue, retry, or cancel it. Create it when work starts; it begins running with a server timestamp.

curl -X POST https://api.flowyn.dev/v1/agent-runs \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-ticket-1042" \
  -d '{
    "agent_id": "7d0f6c1e-2b1a-4c55-9f53-1a2b3c4d5e6f",
    "external_run_id": "ticket-1042"
  }'

Finish a run

Report the one terminal outcome. error is required for failed and rejected otherwise. Reporting the same outcome again returns the stored run unchanged; a different outcome is 409 agent_run_terminal.

curl -X POST https://api.flowyn.dev/v1/agent-runs/3b9d2f7a-8c41-4e0b-a5d6-0f1e2d3c4b5a/finish \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: finish-ticket-1042" \
  -d '{
    "status": "failed",
    "error": {
      "code": "provider_error",
      "message": "Provider rejected the request."
    }
  }'

Status values

Status	Meaning
running	Your runtime reported that the run started.
succeeded	Your runtime reported success.
failed	Your runtime reported failure with a code and message.
cancelled	Your runtime reported that it stopped the run. Flowyn did not cancel anything.

Rules worth knowing

The agent must be active in the same environment to start a run. A run whose agent is archived later can still finish.
external_run_id is optional, unique per agent, and immutable. Use your framework's thread or job id.
A live run needs an API key; a signed-in user can create runs in test only.
Send Idempotency-Key on create and finish so retries are safe.

Read runs

bash

curl https://api.flowyn.dev/v1/agent-runs/3b9d2f7a-8c41-4e0b-a5d6-0f1e2d3c4b5a \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

curl https://api.flowyn.dev/v1/agent-runs?agent_id=7d0f6c1e-2b1a-4c55-9f53-1a2b3c4d5e6f&status=failed \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Lists are newest first, at most 100 per page, with next_cursor for the next page.

Next step

Attach telemetry to the run: Traces and steps.