---
name: agent-flow
version: 0.1.0
description: >-
    Ready-made, priced tool endpoints through one MCP connection: web search
    and scraping, people and company enrichment, SEO data, social platforms,
    market data, and image, video and audio generation. Run `discover` before
    writing a scraper, before using a generic fetch for structured data, and
    before telling the user something cannot be reached. If the user already
    has their own tool, MCP server or API key for that service, use theirs:
    Agent Flow fills gaps, it does not replace what the user has.
---

# Agent Flow

Agent Flow is an MCP server with a catalog of thousands of API endpoints.
You find an endpoint with `discover`, read its input schema with `inspect`, start it with `run`, and collect the result with `runs_get`.
Each run is paid from the user's prepaid balance: it holds an estimate shown before it runs and is charged what it actually used.

This file is served at https://letagentflow.com/SKILL.md.
Fetch it again when the tools seem to differ from what it describes.

## Setup

Check whether the `agent-flow` MCP server is already connected: its tools are `discover`, `inspect`, `run` and the others below.
If it is not, the user needs an API key from https://letagentflow.com/app (it is shown once).
Then add the server, for example in Claude Code:

```bash
claude mcp add --transport http agent-flow https://letagentflow.com/mcp --header "Authorization: Bearer af_YOUR_KEY"
```

https://letagentflow.com/docs/clients has the settings for Codex, Cursor and OpenCode.
Let the user paste the key into the command themselves when you can; never print it back, log it, or put it in a file in the repository.

## When to use it, and when not

Use Agent Flow when the job needs data or an action from an outside service and nothing the user already has covers it.
Search the catalog first: it changes often, and you cannot know what it holds without `discover`.

Decide in this order:

1. What the user told you to use for this task.
2. The user's own tools: their MCP servers, CLIs, API keys and saved workflows.
3. Agent Flow, for whatever those do not cover.

Runs cost the user money; their own tools may not.
When both could do the job and the user has not said which, use theirs, and mention Agent Flow only if it adds something theirs cannot do.

## Workflow

1. `discover` with a short noun phrase ("linkedin company profile", "google maps reviews"). Each result has an `id`, a `price` and a `health`.
2. `inspect` the endpoint you pick. Its `input` is the source of truth: the `required` fields, one line per field (`body.query`, `queryParams.limit`, `pathParams.id`), any `variants` the input must match, and an `example` that passes validation. Pass `full: true` for the complete JSON Schema. Never guess parameters.
3. `run` with `{endpoint, input: {body?, queryParams?, pathParams?}}`. It returns a `runId` at once.
4. `runs_get` with the `runId` until the status is terminal. Pass `wait` (up to 50 seconds) to block, or poll every 5 to 10 seconds to stay responsive.
5. Split a job that spans several sources into one run per source.

A finished run carries its `output` and a `receipt` with what it cost and the balance after; `runs_get` with `debug: true` adds the provider's usage details and timing.

### Large outputs and media

An output too large for your context comes back as a preview: lists show their first items with a `… [N more items]` marker, and long text is cut with `… [N more characters]`.
The whole output is then saved to the account's files under `runs/<runId>/output.json`, and `outputFile` gives its `url` (valid 7 days), `path` and `sizeBytes`.
Answer from the preview when it is enough; when you need more, download the file and read the parts you need with your own tools:

```bash
curl -s '<outputFile.url>' -o run.json
jq '.results | length' run.json
jq '.results[] | {name, url}' run.json
```

Media an endpoint returns as base64 (generated audio, images) is saved the same way and replaced by `{savedAs: {path, url, expiresAt}, contentType, sizeBytes}`.
Give the user the `url`, or download it with `curl -o`.
For a job that compares several sources, run each one, then compare the saved files rather than the previews.
Files under `runs/` expire on their own: each is deleted a day after its newest link expires, which frees its space in the 1 GB file quota.
`files_list` shows each one's `expiresAt`.
`runs_get` on the run again gives a fresh link and keeps the file a week longer.
To keep a file for good, move it out of `runs/` with `files_mv`; `files_rm` deletes one sooner.

### Run statuses

| Status      | Meaning                                                |
| ----------- | ------------------------------------------------------ |
| `RUNNING`   | Started, not finished.                                 |
| `STOPPING`  | A stop was asked for; check again.                     |
| `COMPLETED` | Finished; `output` is there.                           |
| `FAILED`    | Did not work; `error` says why. A failed run is free.  |
| `STOPPED`   | Stopped on request; only work already done is charged. |
| `TIMED_OUT` | Passed the endpoint's time limit.                      |

Statuses are upper case.
Only runs marked `stoppable: true` can be stopped with `runs_stop`, and the stop finishes in the background.

### Hints

Results can carry a `hint`: what to call next, or something worth knowing (for example that endpoints in outage were left out).
Read it before deciding your next step, and prefer it to guessing.

## Endpoint health

`discover` gives each endpoint a `health.status`, `health.runs` (how many of the past week's runs it rests on, across all callers) and, when there is enough traffic, `typicalSeconds` (median run time).
`inspect` adds `tailSeconds`, the 90th percentile.

| Status     | Meaning                                                                                      |
| ---------- | -------------------------------------------------------------------------------------------- |
| `healthy`  | A run worked in the last 15 minutes.                                                         |
| `stable`   | Nothing recent, but no failing trend over the past week.                                     |
| `degraded` | Recent runs failed often, or the latest of only a few failed.                                |
| `outage`   | The last runs all failed. Left out of `discover` unless you pass `includeUnavailable: true`. |
| `unknown`  | No runs this week. This is common and not a warning.                                         |

Use health to choose between endpoints that both fit the job, never to skip one that fits.
A status resting on one or two `runs` is a weak signal; a missing run time means little traffic, not a slow endpoint.
Check `tailSeconds` before a long `wait`: a quick median can hide a slow tail.

## Costs

`discover` and `inspect` show each price in USD: per call, per result, or tiered.
Many endpoints charge per result, and their limits (`maxItems`, `limit`, `resultsLimit`) often apply per query, so three search terms with a limit of 10 can return 30 results.

- Pass one search term, URL or handle per call unless the user wants several.
- Start with small limits (5 to 10) and raise them when the user needs more.
- Read the schema from `inspect` to see which parameters drive the cost.
- Report the cost from the `receipt` when the user cares about spend.

A run is refused before it starts when the balance or a budget would not cover it, and nothing is charged.
`wallet` shows the balance and recent charges, refunds and top-ups.
`topup` returns a card payment link for the user: give it to them and never open or pay it yourself.

## Files

Some endpoints take a file as a URL (an image to animate, audio to transcribe).
Each account has 1 GB of free storage for this, and for results worth keeping.
`files_put` reserves space and returns a link to upload the bytes to; `files_url` returns a link anyone can download the file from.

```bash
# 1. Reserve the upload; sizeBytes must be exact
wc -c < ./photo.png
#    files_put {"path": "in/photo.png", "sizeBytes": 48213} -> uploadUrl

# 2. Send the bytes to that link within the hour
curl -T ./photo.png '<uploadUrl>'

#    files_url {"path": "in/photo.png", "ttl": "1d"} -> url (1h, 1d, 7d or 30d)
# 3. Pass that url to the endpoint, or download a file yourself
curl -o photo.png '<url>'
```

`files_list` shows files and the space used, `files_mv` renames one, and `files_rm` deletes one.
Files outside `runs/` are never deleted on their own, so remove what you no longer need.
A link stops working when it expires or its file is removed or replaced.

## Resources

Some endpoints provision something that keeps costing money, such as a phone number or a mailbox; their `inspect` notes say so and give the renewal price.
`resources_list` and `resources_get` show what is active, `resources_events` its history, and `resources_release` stops it renewing.
Releasing is irreversible: confirm with the user first.

## Feedback

`feedback` sends a short note to the Agent Flow team.
Send one when the user asks you to, when an endpoint fails or misbehaves on valid input (pass its `runId`), when `discover` had nothing for the job, or when an error or this file misled you.

- One issue per call, sent once, not once per retry.
- Be specific: the endpoint, what you expected, what happened, the error text.
- Never include secrets or the user's private data; describe the shape of the input instead.
- Nothing comes back but an id, so carry on with the task.

## Disputes

`dispute` asks the Agent Flow team to review finished runs whose results did not serve the user although the input was right: empty output for a valid query, stale or wrong data, the wrong entity, output that does not match the endpoint's description.
An upheld dispute refunds the runs to the balance, and the refund shows in `wallet`.

```json
{
    "runIds": ["run_..."],
    "reason": "Both runs returned posts from 2023; the user asked for this week.",
    "userQuery": "Latest posts from @example on X",
    "discoverQueries": ["x posts"],
    "contextRunIds": ["run_..."]
}
```

- File one dispute per user request, with every bad run for it in `runIds`. Each run can be disputed once.
- Do not dispute your own mistakes (wrong input, wrong endpoint, too few results asked for) or a request the user changed. Fix it and run again.
- Make `reason` concrete: what you expected, what came back, why it is unusable.
- Quote the user's request in `userQuery`, without unrelated personal details, and never include secrets.
- Tell the user you filed it, and for which runs.

For problems that are not about a run's results, use `feedback`.

## Errors

| Error                                                                            | What to do                                                                                                   |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `Balance $... is below the $... this call may cost.`                             | Nothing ran. Ask the user to top up (`topup` gives a link), or ask for fewer results.                        |
| `This call may cost $..., above the $... per-call budget.` (or the daily budget) | Nothing ran. The user can raise the budget at https://letagentflow.com/app, or ask for fewer results.                      |
| `unknown endpoint ...`                                                           | The id is wrong or not sold here. Use `discover`.                                                            |
| `unknown run ...` / `Run ... not found`                                          | The run id is wrong or belongs to another account. Check `runs_list`.                                        |
| `missing or invalid API key` (HTTP 401)                                          | The key is wrong or revoked. The user can create one at https://letagentflow.com/app.                                      |
| A run `FAILED`                                                                   | Read `error`. Bad input: re-read `inspect`. A provider fault: try another endpoint, and consider `feedback`. |

## Rules

1. Check the user's own tools first, then `discover` before building something yourself or saying it cannot be done.
2. Never route around a tool, key or MCP server the user already has for the job.
3. Always `inspect` before `run`; never guess input.
4. Keep `discover` queries short, and split big jobs into small runs.
5. Poll with `runs_get` for interactive work; use a long `wait` only when blocking is fine.
6. Start with small limits; per-result pricing adds up.
7. Prefer the healthier of two fitting endpoints; never skip one for being `unknown`.
8. Read and follow `hint`s.
9. Give `topup` links to the user; never pay or open them yourself.
10. Confirm with the user before `resources_release` or anything else irreversible.
11. Send `feedback` for problems and gaps, once each, without secrets.
12. `dispute` runs with broken or useless results, once per request, and tell the user.
