Agent infrastructure: overview and quickstart

Register an agent you deploy yourself, record its runs, send traces, read its model usage, and ask a person to approve an action, all through the Flowyn REST API.

Flowyn is the infrastructure around your agent, not the intelligence inside it. Your agent runs wherever you deploy it, with any framework and any model provider. Flowyn records its identity, its runs, its traces and steps, its model usage, and the decisions people make about it.

What you need

A Flowyn API key for the test environment (flw_test_…) with the read and run abilities. Keep it in your agent's server environment.
An agent you already run: OpenAI Agents SDK, LangGraph, CrewAI, Mastra, PydanticAI, or your own Python or Node.js code. There is no plugin to install.

The model

Resource	What it is	Endpoint
Agent	A registered identity for one agent you deploy	`/v1/agents`
Run	A record of one execution your runtime reports	`/v1/agent-runs`
Trace and span	Telemetry your runtime sends; spans in a run-linked trace are the run's steps	`/v1/agent-telemetry`
Model usage	Tokens, latency, and cost totalled from model steps	`/v1/agent-telemetry/usage`
Approval	A decision a signed-in person records for a running run	`/v1/agent-approvals`
Provider connection	An encrypted OpenAI key stored per environment	`/v1/provider-connections`

1. Register the agent

Give the agent a name and, optionally, the id you already use for it. Flowyn returns a stable agent id.

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"
  }'

2. Record that a run started

Your agent is already running on your infrastructure. This call records that fact and returns a run id to attach telemetry and approvals to.

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"
  }'

3. Send traces

The root span carries the run_id. Child spans of kind generation are model steps; kind tool are tool steps. Each item gets its own outcome.

curl -X POST https://api.flowyn.dev/v1/agent-telemetry \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "event_id": "0b8d6f1e-5a43-4c2e-9d11-7f3c2a1b0e01",
        "emitted_at": "2026-09-30T10:00:04Z",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_id": "00f067aa0ba902b7",
        "name": "handle-refund",
        "kind": "span",
        "started_at": "2026-09-30T10:00:00Z",
        "status": "running",
        "agent_id": "7d0f6c1e-2b1a-4c55-9f53-1a2b3c4d5e6f",
        "run_id": "3b9d2f7a-8c41-4e0b-a5d6-0f1e2d3c4b5a"
      },
      {
        "event_id": "1c9e7a2f-6b54-4d3f-8e22-8a4d3b2c1f02",
        "emitted_at": "2026-09-30T10:00:04Z",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_id": "5c1a9e7d3b2f4a60",
        "parent_span_id": "00f067aa0ba902b7",
        "name": "classify-request",
        "kind": "generation",
        "started_at": "2026-09-30T10:00:00.2Z",
        "ended_at": "2026-09-30T10:00:01.1Z",
        "status": "succeeded",
        "provider": "openai",
        "model": "gpt-4.1-mini",
        "input_tokens": 812,
        "cached_input_tokens": 512,
        "output_tokens": 64
      },
      {
        "event_id": "2d0f8b3a-7c65-4e4a-9f33-9b5e4c3d2a03",
        "emitted_at": "2026-09-30T10:00:04Z",
        "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
        "span_id": "9e2d4b6a8c0f1e35",
        "parent_span_id": "00f067aa0ba902b7",
        "name": "lookup_order",
        "kind": "tool",
        "tool_call_id": "call_7Hq2",
        "started_at": "2026-09-30T10:00:01.2Z",
        "ended_at": "2026-09-30T10:00:01.5Z",
        "status": "succeeded"
      }
    ]
  }'

4. Inspect model and tool steps

Read the trace back as a flat list of steps with parent ids, durations, tokens, cost, and errors. The dashboard shows the same trace under Traces.

cURL

curl https://api.flowyn.dev/v1/agent-telemetry/4bf92f3577b34da6a3ce929d0e0e4736 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

5. Understand model usage

Read per-Agent usage through the trace root: child generations count even without agent_id; rootless or unlinked traces are excluded. Optional 24-hour thresholds warn on observed usage greater than or equal to the threshold, computed on request. Missing and unpriced contributions stay visible; other windows are analysis only.

cURL

curl https://api.flowyn.dev/v1/agent-telemetry/usage?agent_id=7d0f6c1e-2b1a-4c55-9f53-1a2b3c4d5e6f&last=24h&group_by=model&bucket=hour \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

6. Ask a person to decide

Create an approval request for the running run. It is pending until a signed-in person approves or rejects it in the Flowyn dashboard.

curl -X POST https://api.flowyn.dev/v1/agent-approvals \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: approval-refund-1042" \
  -d '{
    "run_id": "3b9d2f7a-8c41-4e0b-a5d6-0f1e2d3c4b5a",
    "title": "Refund order 1042",
    "description": "Refund 19.99 USD to the original card.",
    "expires_in_seconds": 3600,
    "request_key": "refund-1042"
  }'

7. Continue according to your runtime

Your agent polls the approval with backoff, reads approved or rejected, and decides what to do. Flowyn never blocks, pauses, or resumes it.

curl https://api.flowyn.dev/v1/agent-approvals/5c1f7a52-0d2e-4b6a-8a4f-2b7c9d1e3f40 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

8. Report the outcome

Report the run's one terminal outcome. The same outcome again is a no-op; a different one is rejected.

cURL

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": "succeeded"
  }'

9. Inspect the result

Read the run, its traces, and its approvals by id. Telemetry is kept for 30 days; the run record stays.

cURL

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-telemetry?run_id=3b9d2f7a-8c41-4e0b-a5d6-0f1e2d3c4b5a \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

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

In the dashboard

Traces, Model usage, Approvals, and Provider connections have their own pages in the Flowyn dashboard. Approval decisions are made there, by a signed-in person.

What Flowyn does not do

Host, deploy, or execute your agent
Run model inference or proxy your model calls
Store prompts, completions, tool arguments, or tool results
Provide agent memory or a vector database
Pause, resume, signal, or cancel a running agent
Enforce an approval inside your runtime

Next step

Read Agents and runs, then Traces and steps.