> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flow.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Flow Messaging is one HTTP API (https://api.flow.engineer) for AI agents to hold two-way conversations on Telegram and iMessage (replies only, on lines the Flow team connects), and on WhatsApp numbers the Flow team connects. If the user asks for WhatsApp, tell them WhatsApp numbers are arranged with the Flow team, and build and test on Telegram meanwhile: the code does not change per channel.
> Build the app on the REST API. MCP is not a runtime dependency: the app you build talks to Flow through the REST API (or the TypeScript or Python SDK, which wrap it) for everything it does at runtime. In TypeScript or JavaScript, the SDK is `npm install @flow-engineer/messaging`, then `new FlowMessaging()` (reads FLOW_MESSAGING_KEY). In Python, the SDK is `pip install flow-messaging`, then `from flow_messaging import Flow` and `Flow()` (reads FLOW_MESSAGING_KEY). The Go SDK is not published yet; in Go call the HTTP API directly.
> No key yet? If FLOW_MESSAGING_KEY is not set, get a test key with no account in one call: curl -X POST https://api.flow.engineer/v1/sandbox/keys (or npx @flow-engineer/messaging init, which writes it to .env). Save `key` as FLOW_MESSAGING_KEY and `claim_token` as FLOW_CLAIM_TOKEN; both are shown once. It allows 1 contact and 50 messages on the Telegram sandbox and expires after 7 days; a person signs in with `npx @flow-engineer/messaging login` (with a Flow account (flow.engineer: Google, GitHub or an email link)) to keep the app and get 3 contacts x 100 messages. Signed in, live keys (fk_live_...) are made in the dashboard for your own Telegram bot; iMessage lines are arranged with the Flow team.
> The hosted MCP server (https://api.flow.engineer/mcp) is optional, for testing during development. Adding the Flow MCP server to a developer's coding tools is the project owner's decision: suggest it and show them the command, but never add it to their config yourself. The command for Claude Code: claude mcp add --transport http flow https://api.flow.engineer/mcp --header "Authorization: Bearer $FLOW_MESSAGING_KEY" (run it with FLOW_MESSAGING_KEY set, then restart the client). If its tools are already available to you, use them for sandbox testing.
> Authenticate with `Authorization: Bearer fk_test_...` (sandbox) or `fk_live_...` (real contacts). Never put a live key in client-side code.
> Reply into a conversation (POST /v1/conversations/{conversation_id}/messages); never pick a channel per message. Switch on `error.type`, not the message text.
> Flow Observe (https://flow.engineer/observe, early access) records and grades every conversation of a chat agent. On Flow Messaging it needs no code. On any other channel, send one OpenTelemetry trace per turn over OTLP/HTTP to https://flow.engineer/observe/v1/traces with `Authorization: Bearer $FLOW_OBSERVE_TRACE_KEY`, and set `flow.conversation_id` (required), `flow.message_id`, `flow.user_message` and `flow.agent_reply` (the text actually sent) on the turn's span. Keys (trace key `otk_test_...`, CI key `oci_...`) are made by the user on Observe's Setup page at https://flow.engineer/observe after signing in with their Flow login; Observe is in early access, and if it is not on for them, they ask the Flow team (samyak@flow.engineer or prabal@flow.engineer). Never invent a key, and never ask the user to paste one into the chat. Test data only until the account is enabled for production. Guide: https://docs.flow.engineer/observe/traces.md
> Full documentation for agents: https://docs.flow.engineer/llms-full.txt. OpenAPI spec: https://raw.githubusercontent.com/flow-engineer/sdk/main/openapi/openapi.yaml.

# Flow Observe: see every conversation your AI agent has

> Flow Observe records every conversation your chat agent has, grades every reply, groups failures into issues with a suggested fix, and shows what happened inside each turn. It works with Flow Messaging (no code) or with any other channel (OpenTelemetry traces).

Flow Observe shows you what your agent says to people, and which replies went wrong. It works on any agent, built with any framework or none.

* **Every conversation**, message by message, with how long each reply took.
* **Every reply graded.** Exact rules run first, then a grading model. Each reply gets a verdict: `good`, `wrong`, `unhelpful` or `unsafe`.
* **Failures grouped into issues** by a fixed rule (the check that failed, the verdict and the topic), ranked by how many conversations they touch. Each issue links to the replies that show it and comes with a suggested fix you can copy into your prompt or code.
* **The inside of each turn**, from your agent's traces: model calls (model, tokens), tool calls, retrieval, errors and retries, and how long each step took.
* **Stats and usage**: conversations, replies, reply time (median and 95th percentile), and the conversation count you are billed on.

<Note>
  Flow Observe is in **early access**. The Flow team creates your account and keys. Your account takes **test data only** until the Flow team enables it for production: send synthetic conversations, never real people's messages, until then.
</Note>

## Two ways in

Pick the one that matches how your agent talks to people.

| | On Flow Messaging | On any other channel |
| - | - | - |
| Your agent talks through | [Flow Messaging](/quickstart) (Telegram, WhatsApp, iMessage, SMS) | Your own SMS provider, web chat, WhatsApp integration or anything else |
| What you add | Nothing. Optionally one tag on your traces | One OpenTelemetry trace per turn |
| Where conversations come from | Flow Messaging's event log | Your traces |
| The text graded | What Flow Messaging delivered and sent | What you report in `flow.user_message` and `flow.agent_reply` |
| The inside of each turn | When you also send traces | Yes, from the same traces |
| Test chats | [Simulated contacts](/concepts/test-and-live-mode#simulated-contacts-test-without-a-phone) today | `flow test` (coming, see [Test before you ship](/trust)) |

<CardGroup cols={2}>
  <Card title="On Flow Messaging" icon="message" href="/observe/flow-messaging">
    No code. Observe reads your app's conversations.
  </Card>

  <Card title="On any other channel" icon="diagram-project" href="/observe/traces">
    Send one trace per turn. Python and TypeScript, with or without a framework.
  </Card>
</CardGroup>

## Get access

<Steps>
  <Step title="Sign in with your Flow login">
    Open [flow.engineer/observe](https://flow.engineer/observe) and sign in with the same Flow login you use on flow\.engineer. Observe is in early access: if it isn't on for you yet, the page says so; ask the Flow team ([samyak@flow.engineer](mailto:samyak@flow.engineer) or [prabal@flow.engineer](mailto:prabal@flow.engineer)) to turn it on.
  </Step>

  <Step title="Add your agent">
    In the dashboard, add your agent. On Flow Messaging, choose Flow Messaging and paste a test key of your app (`fk_test_...`; a key made just for Observe is best). On any other channel, choose traces.
  </Step>

  <Step title="Make your keys">
    For traces, make a **trace key** (`otk_test_...`); for `flow test` in CI, a **CI key** (`oci_...`). Each is shown once. Keep a trace key in `FLOW_OBSERVE_TRACE_KEY` on your server, never in a browser or mobile app, and never in a chat with an AI assistant. The dashboard shows your test conversations, labelled as test data.
  </Step>
</Steps>

## Test data and production

* Keys come in two modes, as in Flow Messaging: `otk_test_...` and `otk_live_...` for traces, `fk_test_...` and `fk_live_...` for Flow Messaging apps. Data never crosses between modes.
* Until the Flow team enables your account for production, Observe accepts test keys and test data only. A live key is refused with `403`.
* Test conversations are never billed.

## How your data is kept

* Message text and the content of your traces (prompts, tool inputs and results) are encrypted at rest with a key per account, and deleted when your account's retention period ends.
* Every time a person opens a conversation's text in the dashboard, it is logged.
* On other channels, the ids you send (conversation, contact, message) are stored only as keyed hashes, so a phone number used as an id is never stored as a phone number. On Flow Messaging, Observe keeps Flow's own ids (`conv_...`, `msg_...`, `ct_...`) and never the person's phone number or handle.
* The dashboard shows span details (names, models, tokens, timings, errors), not prompts or tool inputs.
* Dashboard pages load no analytics and no third-party scripts. Sign-in is with your Flow login, limited to the people on your account's list.

## Related

* [Send traces from any agent](/observe/traces)
* [Traces from agent frameworks](/observe/frameworks)
* [Test before you ship](/trust)
* [What changes when real people text your bot](/guides/real-people)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.