> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Model access for agents

> Your agent calls Anthropic or OpenAI through StackShift with a short-lived token. No provider key is ever in the agent.

> [!NOTE]
>
> **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

**Step 1**

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

**Step 2**

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.

**Step 3**

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.

**Step 4**

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

**Step 5**

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.

```ts TypeScript theme={null}
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.' }],
})
```

```python Python theme={null}
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”.

```bash theme={null}
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

> [!TIP]
>
> 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

> [!WARNING]
>
> * 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.

## Related guides

> [card] [Budgets, stopping and runaway protection](https://docs.stackshift.cloud/ai-features/hosted-agents-budgets.md)
>
> Three budgets, a Stop button that halts everything at once, and layers that stop an agent that loops or fails.

> [card] [The agents SDK for TypeScript and Python](https://docs.stackshift.cloud/ai-features/hosted-agents-sdk.md)
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.