Docs / Tutorials
Tutorial: from a blueprint to your app
Build a blueprint that reviews pictures, test it on cases you know, publish it as an endpoint and call it from your own app.
In this tutorial you build a small service, prove that it works, and put it behind your own app. The example reviews pictures that users upload and decides which are acceptable, but the steps are the same for any blueprint: a nightly simulation sweep started by CI, a report made on request, a dataset cleaned when new files arrive.
The three parts are the three things EsaSim is for: build it, prove it, ship it.
Before you start
- A Pro or Enterprise workspace (endpoints are part of those plans), with GitHub linked and one worker paired with Run code from projects on.
- A language model for the review: an EsaSim model (billed per token from prepaid credits) or your own key for a provider. See AI agents.
- A few pictures you already know the right answer for, reachable by link.
Part 1: build it
- Make a project, for example Picture review, and open its Blueprint tab.
- Add a Download files block. It takes links in its Sources setting, one per line, and gives the files to the next block.
- Add an LLM block and choose where the model runs.
- Add an Agent block. Wire Download files › Files to its Data input and the LLM to its LLM input. Set Allowed labels to
ok, not_okand write the task in Task for each item: what makes a picture not acceptable in your app, in plain words. - Add a Table view on the Agent's Decisions, so you can read each decision with its label, confidence and reasoning.
Or ask an AI assistant: "Build a flow that downloads the pictures at the links I give, has an agent label each as ok or not_ok with its reasoning, and shows the decisions as a table." See Build a study with an AI assistant. Or write the blueprint as a file in your own editor: A project in code.
Part 2: prove it
Before any user's picture reaches it, run it on cases you know.
- Put the links of your known pictures in Sources: some clearly fine, some clearly not, and the borderline ones you care about most.
- Press Run and read the table on the View page. For each wrong decision, read the agent's reasoning: it usually says what the task prompt left unclear.
- Change the prompt or the labels and run again. Each run keeps the version that made it, so you can see which change fixed which case and whether it broke another.
- Keep the known pictures as your test set. Run it again whenever you change the prompt or the model.
When the decisions are right on the cases you know, choose Publish: this makes a numbered version that never changes.
Part 3: ship it
Make the endpoint
- Open the project's API tab and choose the blueprint.
- Name it, and choose the version it runs. Fixed is the safe choice for an app: publishing a new version later changes nothing until you make a new endpoint for it.
- Under Inputs your app may set, tick Sources of the Download files block and name it
sources. Leave the prompt and the labels unticked: the app must not be able to change the rules. - Choose Make the endpoint and copy the key. It is shown once.
Call it from your app's server
Python:
import os, requests
ENDPOINT = "https://<your EsaSim address>/api/v1/endpoints/<id>"
HEADERS = {"Authorization": "Bearer " + os.environ["ESASIM_ENDPOINT_KEY"]}
def review(picture_urls):
run = requests.post(ENDPOINT + "/runs", headers=HEADERS, timeout=40,
json={"inputs": {"sources": "\n".join(picture_urls)}, "wait": 25}).json()
while not run.get("done"): # still going: ask again
run = requests.get(run["url"], headers=HEADERS, params={"wait": 25}, timeout=40).json()
if run["status"] != "succeeded":
raise RuntimeError(run.get("error", "the review did not run"))
decisions = next(o for o in run["outputs"] if o["path"].endswith("decisions.csv"))
return {row["item"]: row["label"] for row in decisions["rows"]}
JavaScript (Node):
const ENDPOINT = "https://<your EsaSim address>/api/v1/endpoints/<id>";
const headers = { Authorization: "Bearer " + process.env.ESASIM_ENDPOINT_KEY, "Content-Type": "application/json" };
export async function review(pictureUrls) {
let run = await (await fetch(ENDPOINT + "/runs", { method: "POST", headers,
body: JSON.stringify({ inputs: { sources: pictureUrls.join("\n") }, wait: 25 }) })).json();
while (!run.done) run = await (await fetch(run.url + "?wait=25", { headers })).json();
if (run.status !== "succeeded") throw new Error(run.error || "the review did not run");
const decisions = run.outputs.find(o => o.path.endsWith("decisions.csv"));
return Object.fromEntries(decisions.rows.map(r => [r.item, r.label]));
}
The Agent's table has the columns item, label, confidence and reason; for another blueprint, the column names of rows are those of the table it makes. API endpoints lists every call, answer and error.
What to build around it
- Send pictures in batches. Each call starts a run of the whole blueprint, which takes seconds to minutes. Collect new uploads and send them together every minute or so, and show them as "under review" until the answer comes.
- Keep the key on your server. Never in a web page or a phone app: it gives the right to start runs on your workers.
- Keep a worker on. Runs go to the workers of the person who made the endpoint. With none online, calls answer 409 or wait in the queue.
- Decide what happens on failure. If a run fails or the limit of calls an hour is reached, hold the pictures and try again later; do not approve by default.
Change it safely later
- Edit the blueprint (on a branch, if colleagues review your changes). The app keeps getting the published version.
- Run your test set of known pictures on the new draft and compare with the last run.
- Publish the new version. An endpoint on always the latest uses it from the next call; for a fixed one, make a new endpoint, point the app at it, and remove the old one when nothing calls it any more.
Every call is a run in the project's Runs, with its inputs, its version and its files, and in the audit log under the endpoint's name: when someone asks why a picture was refused, the answer is on record.