# The Lamalo Engine guide

**Engine version:** `3.13.1`

This is the page to read first, by a person or by an AI. It says what the engine is, how to reach it, and
which page answers which question. It is public: no key is needed to read it or any page it links to.

## What the engine is

One API to call a wide range of AI models across providers, built in three layers. Each layer is its own
server, and one key opens all three.

| layer | what it does | address |
| --- | --- | --- |
| 1. Models | Calls a model: chat, web search, images, audio, video, embeddings, OCR… OpenAI-compatible, so any OpenAI SDK works against it. | `https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1` |
| 2. Tools | Fixed-function tools over MCP: read and write a user's mail, drive, calendar, spreadsheets, Teams; read documents; retouch images; run pipelines. | `https://lamalo-engine-mcp-82364605132.europe-west1.run.app/mcp` |
| 3. Agents | Autonomous agents over A2A: give one a goal, it plans, uses tools and decides when it is done. | `https://lamalo-engine-agents-82364605132.europe-west1.run.app/agents` |

Layer 1 is a **superset** of OpenAI's API: every OpenAI field is accepted, and the engine adds a `lamalo`
object for what OpenAI has no word for — letting the engine pick the model (`auto`), restricting which
models it may pick, and tagging calls so you can read their usage back later.

## The three rules people get wrong

1. **It is called from a backend, never from a browser.** The key belongs to your application, not to your
   users. Your backend calls the engine on their behalf.
2. **The engine reports usage and rates, never a price.** Each response carries the rate card in force
   (`lamalo.pricing`) and the usage; your application multiplies.
3. **`auto` is always available.** If a call with `auto` is refused, the error code says why — most often
   `price_affecting_param_under_auto`: a parameter whose price depends on the model needs a named model.

## Using the engine from a coding assistant (AGENTS.md / CLAUDE.md)

If you build with a coding assistant (Claude Code, Codex, Cursor…), paste the block below into your
project's `AGENTS.md` or `CLAUDE.md`, or add it straight from the terminal:

```sh
curl -s https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/agents-md.md >> AGENTS.md
```

The assistant then knows where the engine is, how to choose a model, and which mistakes to avoid. The block
is also its own page: [the AGENTS.md block](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/agents-md.md).

## Lamalo Engine

This project calls the Lamalo Engine: one API for many AI models across providers, plus a tools server and
an agents server. Follow these rules whenever you write code that uses it.

**Where it is**

- Models, OpenAI-compatible: `https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1`. Set it as the
  `base_url` of any OpenAI SDK; the request and response shapes are OpenAI's.
- Tools, MCP over Streamable HTTP: `https://lamalo-engine-mcp-82364605132.europe-west1.run.app/mcp`.
- Agents, A2A v1.0: `https://lamalo-engine-agents-82364605132.europe-west1.run.app/agents` lists them.
- When unsure how something works, read
  `https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide.md` (public) before guessing.

**The key**

- One key per application, sent as `Authorization: Bearer <key>`; the same key works on all three servers.
- Read it from an environment variable (for example `LAMALO_API_KEY`). Never commit it, never log it, and
  never ship it to a browser or a mobile app: the engine is called from your backend, on behalf of your users.

**Choosing a model**

- Name a model as `<provider>/<model_id>` (for example `openai/gpt-image-2.5-sunburst`), or send `auto` to
  let the engine choose. Take model ids from `GET /v1/models`; never write one from memory, because models
  are added and retired often.
- Engine-only options ride a `lamalo` object in the request body. With an OpenAI SDK, pass it as
  `extra_body={"lamalo": {...}}`.
- With `auto`, steer the choice with `lamalo.tiers`: `budget`, `latency` and `performance`, each between 0
  and 1.
- A parameter whose price depends on the model only works with a named model. `auto` plus such a parameter
  returns `400` with code `price_affecting_param_under_auto`: it means "name a model", not "`auto` is
  unavailable".

**Cost**

- The engine reports usage and the rates in force (`lamalo.pricing` on the response); it never computes a
  price. Compute prices yourself from those two, and never show a price you did not compute that way.
- Put `lamalo.metadata` on every call, with your own `reconciliation_id` and `env`, so you can read a
  turn's calls back with `GET /v1/usage?reconciliation_id=…&env=…`.

**Errors**

- Errors always look like OpenAI's: `{"error": {"message", "type", "code"}}`. Branch on `error.code`, never
  on the message text.
- Log the `X-Lamalo-Error-Id` response header, and quote it when reporting a problem with the engine.

**Slow work**

- Video generation, avatar videos, deep search, video analysis and pipeline runs are jobs: the first call
  returns an id straight away, and you check on it until it finishes. Do not wait for the result in the
  same request.

**Tools (MCP)**

- The tools server always lists exactly two tools: `search_tools` finds a tool, `execute_tool` runs one.
- A tool that acts on a user's own account (mail, drive, calendar…) needs that user's sign-in token. The
  tool's `credential_args` names the arguments your code must fill in itself; never let a model see or
  write them.

**Agents (A2A)**

- `GET /agents` lists the agents; there is no single agent card at the server root. Each agent's card is at
  `/agents/{id}/.well-known/agent-card.json`.
- Sending an agent a message usually returns a task, not an answer: stream it, poll it, or ask to be called
  back.
- The `guide` agent answers questions about the engine itself.

## Which page answers what

| question | page |
| --- | --- |
| How do I call a model, choose one, read errors and cost? | [calling models](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/models.md) |
| How do I make or edit images, speech, sound or music? | [images and audio](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/images-and-audio.md) |
| How do I find and run a tool? | [tools](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/tools.md) |
| How do I find an agent and delegate to it? | [agents](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/agents.md) |
| How do I chain model calls and tool calls into one run? | [pipelines](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/pipelines.md) |
| How do I make a model think harder or less? | [reasoning](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/reasoning.md) |
| Which mail, drive, calendar, chat and sheet tools exist? | [Google Workspace](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/google-workspace.md), [Microsoft 365](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/microsoft-365.md), [spreadsheets](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/spreadsheets.md) |
| How do I make a video or an avatar video? | [video generation](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/video-generation.md), [avatars](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/avatars.md) |
| How do I ask questions about a video, or research the web in depth? | [video analysis](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/video-analysis.md), [deep search](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/deep-search.md) |
| How do I read the text out of a document? | [text extraction](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/text-extraction.md) |
| How do I get a probability instead of a sentence? | [decisions](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/decisions.md) |
| How do I drive a browser or a desktop? | [computer use](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/guide/computer-use.md) |
| What is every layer-1 route, field and status code? | [the OpenAPI spec](https://lamalo-engine-oai-82364605132.europe-west1.run.app/v1/spec.yaml) |

The same list, one line per page, is at
`https://lamalo-engine-oai-82364605132.europe-west1.run.app/llms.txt`. Opening the bare address,
`https://lamalo-engine-oai-82364605132.europe-west1.run.app`, brings you to this page.

## Asking instead of reading

- **The `explain_engine` tool** (layer 2) hands back any page of this guide by its topic name, for free.
  An AI connected to the tools server finds it with `search_tools`.
- **The `guide` agent** (layer 3) answers a question about the engine in plain words and names the page it
  used. It is the first agent in `GET /agents`.

Both need the same key as the rest of the engine; this guide itself does not.