Model access for agents

Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

Goal

Give your agent models, pay for them in AI credits or with your own provider key, and handle each way a call can be refused.

Prerequisites

An agent with the models it may use listed under models: in stackshift.yaml.
AI credits in your account, or your own Anthropic or OpenAI key saved in the agent’s settings.

Workflow

List each model under models: with its provider. A call to a model that is not listed is refused with 403 model_not_allowed.

Choose how the agent pays in payWith: credits or own_key. For own_key, save the key in the agent’s settings. The agent never sees it.

In the agent’s code, use agent.anthropic() or agent.openai(). They return the official clients, already pointed at StackShift and signed in with the run token. Or set the base URLs yourself, as below.

Pass max_tokens on every call. A call without it is refused.

Set budgets for the month and for one run so a mistake cannot spend more than you chose.

What the agent has

Inside the agent, ANTHROPIC_BASE_URL is https://api.stackshift.cloud/ai and OPENAI_BASE_URL is https://api.stackshift.cloud/ai/v1. The credential is a run token: it is bound to this agent and the place it runs, lasts one hour, and a new one arrives with each event. The SDK keeps it in memory and, where it can, in a private file in the agent’s home folder for the official clients. It is never in an environment variable. It stops working the moment the agent is stopped. The endpoints are the ones the official SDKs call: POST /ai/v1/messages (streaming, tool use and prompt caching pass through), POST /ai/v1/responses and POST /ai/v1/chat/completions. Errors come back in the provider’s own error shape.

const anthropic = await agent.anthropic()

const answer = await anthropic.messages.create({
  model: 'claude-sonnet-5-5',
  max_tokens: 1000,
  messages: [{ role: 'user', content: 'Summarise this order.' }],
})

answer = await agent.async_anthropic().messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Summarise this order."}],
)

Paying with credits or your own key

Before each call StackShift reserves credits for the input plus max_tokens at the output price. After the call it settles on what the provider reports. If a stream is cut, it settles on what was seen and releases the rest. Providers today are Anthropic and OpenAI. The agent’s requests go to the provider and model it asked for.

Credits: charged at the same rates as Stackie. One credit is $0.001. Top up in Naira or US dollars from your wallet.
Your own key: StackShift charges no tokens. Your provider bills you. The agent’s budget still counts the call at list price so the number means something, and your account’s own-key spend limits still apply.

Limits per call and per run

max_tokens is required, and calls above 64,000 output tokens are refused by default.
At most 200 model calls in one run.
A run lasts at most 30 minutes by default.

From your own code outside StackShift

Code that does not run as an agent can use the same endpoints with an AI project key that has the scope ai:inference. See “Standalone AI projects and application keys”.

curl https://api.stackshift.cloud/ai/v1/messages \
  -H "x-api-key: $STACKSHIFT_AI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":200,"messages":[{"role":"user","content":"Hello"}]}'

Expected result

Model calls work with the official SDKs unchanged. Each call is metered, counted against the run, month and account limits, and listed on the run’s page with its model, tokens and credits.

Common failures

402 budget_reached with a scope of run, month or account: the run budget, the monthly AI budget or your account credits are used up. At the monthly budget the agent stops itself and you are told.
401 provider_key_refused: “Your Anthropic key was refused. Update it in the agent’s settings.” Your own key was revoked or is wrong.
423 agent_stopped: “This agent is stopped.” Start it from its page.
403 model_not_allowed: the model is not in the agent’s models: list.
413 request_too_large: the request or a tool result is over the limits.
429 loop_detected: “Paused: the same request repeated.” The same prompt and tools were sent more than 5 times in 2 minutes in one run. The agent is paused with the evidence on its page.
503 broker_unavailable with a retry-after: StackShift could not take the call. The official SDKs retry with backoff, and an event whose run fails is delivered again.
A provider outage or rate limit comes back with the provider’s own status and retry-after. StackShift never switches to another provider or model for you.

Budgets, stopping and runaway protection

Three budgets, a Stop button that halts everything at once, and layers that stop an agent that loops or fails.

The agents SDK for TypeScript and Python

The packages @stackshift-cloud/agent and stackshift-agent give your code events, governed actions, StackShift calls, state, model clients and adapters for the Claude Agent SDK and the OpenAI Agents SDK.

​Goal

​Prerequisites

​Workflow

​What the agent has

​Paying with credits or your own key

​Limits per call and per run

​From your own code outside StackShift

​Expected result

​Common failures

​Related guides

Budgets, stopping and runaway protection

The agents SDK for TypeScript and Python

Goal

Prerequisites

Workflow

What the agent has

Paying with credits or your own key

Limits per call and per run

From your own code outside StackShift

Expected result

Common failures

Related guides