AI Agents

Deploy an AI agent that runs your own code on a public endpoint, and call it securely with an invoke token.

An AI Agent is a small app you build in the portal: you write a handle(request) function, we run it in a container, and it gets a public endpoint at POST /invoke. Your code can call our GPU model (billed per token, like the inference API) or bring your own provider key. You edit and redeploy the code in the in-portal Cloud Editor — no build pipeline to set up.

Every /invoke call needs an invoke token

New agents are private by default: their /invoke endpoint requires an invoke token. Send it as Authorization: Bearer ak-live-…. This stops anyone who guesses your endpoint URL from running your agent — which, for an agent on our GPU, would spend your balance. See Call your agent securely below.

Create an agent

Open AI Agents in the portal (/dashboard/cloud-studio/agents) and start the create flow.

Name the agent, pick a starter template (chatbot, rag, langchain, or blank), and choose a provider: alawadi (our GPU, billed per token) or bring your own key for OpenAI, OpenRouter, Google, Anthropic, or Vertex.

On the success screen, copy the invoke token (ak-live-…) now: like an API key, it is shown exactly once. We store only its prefix; if you lose it, rotate it to get a new one.

Your agent's public endpoint is https://<name>-<id>.alawadi.cloud/invoke. The exact URL is on the agent's page in the portal.

Call your agent securely

Send a JSON body — it is passed to your handle(request) function — with the invoke token in the Authorization header. The response wraps your handler's return value in an output field.

export AGENT_INVOKE_TOKEN="ak-live-..."

curl https://my-agent-a1b2c3.alawadi.cloud/invoke \
  -H "Authorization: Bearer $AGENT_INVOKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "مرحبا"}'
# → {"output": {"reply": "..."}}

import os
import httpx

resp = httpx.post(
    "https://my-agent-a1b2c3.alawadi.cloud/invoke",
    headers={"Authorization": f"Bearer {os.environ['AGENT_INVOKE_TOKEN']}"},
    json={"message": "مرحبا"},
)
print(resp.json()["output"])

Responses you should handle:

Status	Meaning
`200`	Success. Your handler's return value is in `output`.
`401`	Missing or wrong invoke token (for a private agent).
`429`	Rate limit hit. Retry after the `Retry-After` header (default 60 requests/minute per agent).
`503`	The agent is still starting or its source failed to load.
`500`	Your `handle()` raised an error.

Public agents

If your agent is meant to be called by anyone — a public chatbot on your website, say — you can make it public when you create it. A public agent serves /invoke without a token. You can still add per-call limits in your own handler code. Keep an agent private whenever it spends your balance or holds a provider key.

Agents created before invoke tokens shipped

Older agents are public (they keep working exactly as before). To require a token, open the agent and rotate its token — that mints the first token and secures the endpoint.

Rotate the token

Rotating mints a fresh invoke token, secures the endpoint (the agent becomes private), and restarts the agent so the new token takes effect. Your inference key and any provider key are left untouched. Do it if a token leaks, or to secure a public/older agent.

In the portal: open the agent → Rotate invoke token → copy the new token.
Over the API: POST /v1/projects/{projectId}/agents/{agentId}/invoke-token/rotate.

The new token is shown once; store it before you close the dialog.

Edit and deploy your code

The agent's source lives in the in-portal Cloud Editor. Edit handler.py, click Deploy, and we roll a new revision. Every deploy is a new revision you can list and roll back to — so a bad change is one click from recovery.

List revisions: GET /v1/projects/{projectId}/agents/{agentId}/revisions
Roll back: POST /v1/projects/{projectId}/agents/{agentId}/rollback with {"revision": <n>}

AI Agents API reference — every endpoint, with schemas.
AI inference overview — the model your agent calls.
Billing and usage — how agent token usage is metered.