Using AI in scripts
Asking the app's AI models for text, JSON with a set shape and embeddings, sending files, handling errors and knowing what each provider does.
The app's scripts call AI through the SDK's ai module. The script picks
the model by the alias name, and the request leaves the platform's server with
the provider's credentials. The script never sees the keys.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Before you start
- The tenant needs an active AI provider with authorised models. See AI providers.
- The app needs an alias for each use the script asks for. Without
model=, the script uses that use's default alias. See App AI models.
What each provider does
| Provider | Text, JSON and tools | Embeddings | Images | Transcription | Speech | Batches |
|---|---|---|---|---|---|---|
| OpenAI | Yes | Yes | Yes | Yes | Yes | Yes |
| Anthropic | Yes | No | No | No | No | Yes |
| Microsoft Foundry | Yes | Yes | Yes | Yes | Yes | No |
| Amazon Bedrock | Yes | Titan and Cohere | Nova Canvas, Titan and Stability | No | No | No |
| Google Cloud | Yes | Yes | Yes | Yes | Yes | Gemini API only |
| OpenRouter | Yes | Yes | Yes | No | No | No |
| OpenAI-compatible | Yes | Depends on the server | Depends on the server | Depends on the server | Depends on the server | No |
A call to a provider that does not do an operation gives the not_supported
error. With any provider, the operation only works with a model that does
it: a text model does not generate images.
Tools and batches are in Tools and batches, and images, transcription and speech in Images and audio.
Asking for text
ai.chat sends a request and returns the model's answer:
from api_manager import ai, log
def main(input):
r = ai.chat(
"Classifica este pedido de suporte: " + input["args"]["pedido"],
system="És um assistente de apoio ao cliente. Respondes numa palavra: urgente, normal ou baixo.",
model="texto",
max_tokens=10,
temperature=0,
)
log("classificação:", r["text"], r["usage"])
return {"prioridade": r["text"].strip().lower()}
| Parameter | What it does |
|---|---|
prompt |
The question. |
system |
The system instruction: the model's role and rules. |
messages |
A conversation, instead of prompt (see A conversation). |
model |
The alias name. Without it, the default text alias applies. |
max_tokens |
The maximum size of the answer. Without it, the alias's value applies, and then the platform's. |
temperature |
From 0 to 2. A low value gives more predictable answers. Without it, the model's value applies. |
files |
Files that go with the question (see Sending files). |
stream |
A name, so that the text appears on the screen of whoever called while the model writes it (see Live answers on screen). |
The result is a dict:
| Key | What it holds |
|---|---|
text |
The text of the answer. |
stop_reason |
Why the model stopped: end, max_tokens, tool_use, refusal or other. |
usage |
The tokens used, in input_tokens and output_tokens. |
model, provider, alias |
Who answered. |
A stop_reason of max_tokens means the answer was cut off. Raise
max_tokens or ask for a shorter answer.
A conversation
To continue a conversation, pass the history in messages, with the
user and assistant roles alternating:
from api_manager import ai
def main(input):
r = ai.chat(
messages=[
{"role": "user", "content": "O meu nome é Ana."},
{"role": "assistant", "content": "Olá, Ana!"},
{"role": "user", "content": "Como me chamo?"},
],
)
return {"resposta": r["text"]}
With both messages and prompt, the prompt goes in as the last user
message. The list can also go as the first argument, without messages=:
ai.chat([...]).
Asking for JSON with a set shape
ai.json asks for the answer in JSON, validates it against a JSON Schema
and returns the JSON already parsed:
from api_manager import ai
ESQUEMA = {
"type": "object",
"properties": {
"nif": {"type": "string", "description": "NIF do cliente, 9 algarismos"},
"total": {"type": "number", "description": "Total com IVA, em euros"},
},
"required": ["nif", "total"],
}
def main(input):
factura = ai.json(
"Extrai o NIF do cliente e o total desta factura.",
schema=ESQUEMA,
files=[input["args"]["factura"]],
)
return factura # {"nif": "...", "total": 123.45}
- The schema describes the shape: the types, the required fields and a
descriptionfor each field. The better the description, the better the answer. - An answer that does not match the schema gives the
invalid_outputerror. The script never receives data with the wrong shape. - Providers that support structured output receive the schema in the request. The others receive it in the system instruction, and the answer is validated all the same.
Sending files
files= sends app files with the request, in ai.chat and in ai.json.
It accepts Upload arguments as they arrive in input["args"], or what
files.store returns:
from api_manager import ai, files
def main(input):
# an Upload argument of an API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# a file the script itself creates
vendas = files.store(b"produto;quantidade\nCadeira;12\nMesa;30\n", "vendas.csv", "text/csv")
melhor = ai.chat("Que produto vendeu mais? Responde só com o nome.", files=[vendas])
return {"estado": estado["text"], "mais_vendido": melhor["text"]}
| Type | How it goes |
|---|---|
| PNG, JPEG, GIF and WebP images | As an image, for models that see images. |
| As a document, for models that read PDF. | |
| Text (txt, csv, json, md, xml and yaml) | As text, before the question. |
Each file can be up to 20 MB, and a request up to 40 MB. A text-only model
refuses images and PDF with the invalid_request error.
Embeddings
ai.embed turns text into vectors, to search by meaning and not only by
matching words:
from api_manager import ai
def semelhanca(a, b):
produto = sum(x * y for x, y in zip(a, b))
normas = (sum(x * x for x in a) ** 0.5) * (sum(y * y for y in b) ** 0.5)
return produto / normas
def main(input):
pergunta = ai.embed(input["args"]["pergunta"]) # one vector
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # one vector por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
One text returns one vector. A list returns a list of vectors, in the same
order, up to 2048 texts per call. Without model=, the default embeddings
alias applies.
The app's aliases
ai.models() returns the app's aliases, each with its name, use, default
mark, provider and model. A script can use it to choose the model while it
runs, or to explain why an alias is missing.
Errors
A call that fails raises ai.Error. The code attribute is the same for
every provider, and the message says what happened:
from api_manager import ai, log
def main(input):
try:
r = ai.chat(input["args"]["pergunta"])
except ai.Error as e:
log("IA:", e.code, str(e))
if e.code in ("rate_limited", "unavailable", "timeout", "connection"):
return {"tentar_mais_tarde": True}
raise
return {"resposta": r["text"]}
| Code | What it means |
|---|---|
not_configured |
The alias is missing, the provider is disabled or the model is no longer authorised. |
rate_limited |
The provider refused because of too many requests. |
timeout |
The provider did not answer within the maximum time. |
unavailable, connection |
The provider is down or could not be reached. |
auth, permission |
The key was refused or does not have permission. |
invalid_request |
The request is not valid for this provider or model. |
invalid_output |
The answer's JSON does not match the schema. |
refused |
The model refused to answer. |
not_supported |
The provider does not do this operation, or the file is of a type that cannot be sent. |
cancelled |
The run ended before the answer. |
max_steps |
ai.run reached the maximum number of steps without a final answer. |
not_found, unknown |
The model or the address does not exist, or another error happened. |
Time limit and logs
- An answer can take tens of seconds. The script's Time limit has to be enough for all the calls: in a script with several, raise it.
- When the run ends, because of the time limit or a cancellation, the requests still waiting are cancelled at the provider.
- Each call writes a line in the run's logs, with the alias, the model and the
duration, for example
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - The platform does not store the text of the requests or the answers, unless the app turns on debugging (see App AI models). The request goes to the app's AI provider, so do not send it personal data without need.
Frequently asked questions
Can I use AI from a widget or from the browser? No. AI exists only in scripts, which run on the server, so the keys never reach the browser. A screen that needs AI calls an API that runs a script.
The script says not_configured and the alias exists. Check that the
alias is for the right use (an embeddings alias does not work for
ai.chat), that the provider is active and that the model is still
authorised in it.
Can I use the OpenAI or Anthropic library directly? You can install it
through the pip panel, but the key would have to live in an app secret,
and the script would lose the aliases and the common error codes. The ai
module exists for that.