How to launch an agentic product

01 / HOW IT WORKS

How it works

An agentic product has two parts: the agent, and the business around it. Gemmein handles the business part: who the person is, whether they can run the tool, what it costs in credits, and where the result is stored. The two meet at one signed run.

Gemmein sends the run and receives the result you report. It never runs, inspects or stores your agent's logic, and never sees the graph, the loop or the keys behind your URL. The person never sees your URL or your keys.

02 / RECEIVE A RUN

Receive a run

You define a tool on provider external, priced in credits, and give it your pipeline's URL. When a person starts it, Gemmein reserves the credit ceiling and posts the signed run directly to that URL, with no relay involved. Your agent does the work, then reports to the run's own URLs with a single-use token.

Gemmein posts the run to your pipelineSigned request · X-Gemmein-Signature

{
  "run": { "id": "run_...", "tool": "research-agent", "kind": "generate",
           "units": "call", "reserved": 20, "createdAt": "..." },
  "params": { "question": "..." },
  "person": { "id": "...", "email": "..." },
  "deadline": "...",
  "complete": { "url": "https://api.gemmein.com/runs/<app>/<env>/<id>/complete", "token": "...", "expiresAt": "..." },
  "progress": { "url": "https://api.gemmein.com/runs/<app>/<env>/<id>/progress" },
  "fail":     { "url": "https://api.gemmein.com/runs/<app>/<env>/<id>/fail" }
}

Your agent reports the resultYour server

// Authorization: Bearer <token>  (single-use, no session)
POST /runs/<app>/<env>/<id>/complete
{
  "text":  "…the agent's answer…",
  "files": [{ "url": "https://…/chart.png", "contentType": "image/png" }]   // images, audio or video
}
// a metered tool (images, seconds or characters) also sends "units": what it metered
// optionally, any number of times before that:
POST /runs/<app>/<env>/<id>/progress   { "progress": 40, "note": "researching" }
// or, if it could not finish:
POST /runs/<app>/<env>/<id>/fail   { "error": "…" }

Gemmein copies the files into the person's sealed files and keeps the text on the run as its result. This per-call tool is charged its 20 credits. Run files must be images, audio or video, up to 200 MB. Any other file type fails the run with 422 result_refused and releases the credit ceiling. The SDK helper g.pipelines.handle(secret, fn) checks the signature, acknowledges the run and makes the complete or fail call in three lines. See the pipeline docs.

03 / FROM THE APP

Start and watch a run

Your app makes two calls: one to start the run, and one to watch it for progress and the result.

ClientJavaScript / Expo

const run  = await g.runs.start("research-agent", { question }, { key: jobId });
const done = await g.runs.watch(run.id, { onUpdate: r => show(r.progress) });
// also: g.runs.get(id) · g.runs.list({ since, limit }) · g.runs.cancel(id)

The key makes the start idempotent, so a retry does not launch the agent twice.

04 / KEYS

Key permissions

Your pipeline needs no Gemmein secret key. It checks each run with the tool's own signing secret (aisk_…, shown once on the tool's page), and it writes back only through the run's single-use completion token. Your agent authenticates to its own providers with its own keys, which never touch Gemmein.

Your agent can finish the one run it received, once, and has no standing access to the rest of your app.

05 / FOR YOUR CODING AGENT

Prompt for your coding agent

Paste this into Cursor, Claude, Bolt or Lovable so your agent sets up the tool, the run handler and the client calls.

Prompt for your coding agentCopy and paste

Read https://docs.gemmein.com/llms.txt and https://docs.gemmein.com/ai. I am building an agentic product. I want sign-in, credits and results handled for me while my own pipeline runs the agent. Show me how to define an external tool priced in credits and receive the signed run directly at my URL (run id, params, credit ceiling, completion token). Use g.pipelines.handle with the tool's own signing secret to verify it, do the work on my own keys, and return the result (text, files, and units on a metered tool) or fail it. On the client, use g.runs.start and g.runs.watch.

npx gemmein devRead the getting-started guide

06 / FAQ

Frequently asked questions

What agent frameworks can I use?

Any. Your pipeline is a URL, so it can be any code in any language or framework: a single model call, a Python script, a LangGraph graph, a CrewAI crew, an n8n flow or a multi-agent loop.

How is an agent run billed?

Gemmein reserves the credit ceiling when the run starts. A per-call tool is charged its price when the run succeeds. A metered tool (images, seconds or characters) is charged for the units you report when you complete the run, never above the credit ceiling. A failed run releases the credit ceiling.