> ## 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.

# The agent block in stackshift.yaml

> Reference for the `type: agent` service: what wakes the agent, how it pays, what it may reach and which actions it has.

> [!NOTE]
>
> **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

## Goal

Describe an agent completely in the repository, so each deploy is reviewable and repeatable.

## Prerequisites

* A `stackshift.yaml` in the folder you deploy, with a service of `type: agent`.
* A `Dockerfile` in the same folder that installs and builds your agent. StackShift builds from it, so there is no build command in `stackshift.yaml`.
* A start command that starts your agent and listens on the port you set, 8080 unless you change it.

## Workflow

**Step 1**

Add a service of `type: agent` with `startCommand`, `port` and an `agent:` block. Other services in the same file keep working.

**Step 2**

Set the agent’s `name`, `level`, what wakes it and how long it sleeps after the last work.

**Step 3**

List the models it may use and how it pays: `credits` or `own_key`. Set the budgets.

**Step 4**

List the StackShift actions it may ask for under `platform:` and its own tools under `actions:`.

**Step 5**

Push and deploy. A version that asks for more than the last one waits for you to activate it.

## An example

```yaml stackshift.yaml theme={null}
apiVersion: stackshift.com/v1
kind: Application
metadata:
  name: mills-supplies
spec:
  services:
    supplies-agent:
      type: agent
      startCommand: node dist/agent.js
      port: 8080
      agent:
        name: Supplies agent
        level: ask_every_time
        wakeOn: [inbox, agreements, schedule]
        sleepAfter: 15m
        schedule: ["0 7 * * 1-5"]
        timeZone: UTC
        models:
          - provider: anthropic
            model: claude-sonnet-5-5
        payWith: credits
        budget:
          aiCreditsPerMonth: 200000
          aiCreditsPerRun: 5000
          computePerDay: { NGN: "5000000" }
        inbox: { prefix: supplies, sendMode: replies }
        agreements: true
        internet: [api.millsco.com]
        platform:
          - mail.agent_inbox.send
        actions:
          - key: lookup_order
            summary: Look up an order by its number
            risk: read
            input:
              type: object
              required: [order_id]
              properties:
                order_id: { type: string, maxLength: 40 }
            output: untrusted
          - key: refund_order
            summary: Refund a customer's order
            risk: ask
            money:
              amountField: amount
              currencyField: currency
              limit: { NGN: "5000000" }
            reachesPeople: true
            input:
              type: object
              required: [order_id, amount, currency]
              properties:
                order_id: { type: string, maxLength: 40 }
                amount: { type: string, pattern: "^[0-9]+$" }
                currency: { type: string, enum: [NGN, USD] }
```

## Fields of the agent block

* `name` (required, up to 80 characters): what the agent is called on its page.
* `level`: `ask_every_time` (default), `safe_changes` or `whole_tasks`. See the levels in “Your agent’s own actions”.
* `wakeOn`: any of `inbox`, `agreements`, `a2a`, `schedule`, `webhook`.
* `sleepAfter`: `5m` to `1h`, or `never`. Default `15m`.
* `schedule` and `timeZone`: up to 10 five-part cron expressions, and an IANA time zone such as `UTC` or `Africa/Lagos`.
* `models`: up to 10 entries, each `provider` (`anthropic` or `openai`) and `model`. A model call for a model not listed is refused.
* `payWith`: `credits` (default) or `own_key`.
* `budget`: `aiCreditsPerMonth`, `aiCreditsPerRun` and `computePerDay` (one currency, `NGN` or `USD`, whole kobo or cents as text).
* `inbox`: `prefix` and `sendMode` (`off`, `replies` or `any`). `agreements: true` turns on agreements for the inbox; the limits stay yours to set.
* `internet`: extra hosts the agent may reach, up to 64.
* `platform`: the StackShift actions the agent may ask for, up to 50. You consent to exactly this list when you deploy.
* `actions`: the agent’s own tools, up to 100.

## Fields of an action

* `key`: lowercase letters, digits and underscores, up to 63 characters.
* `summary` (required, up to 200 characters): shown on approval cards, so write what it does in plain words.
* `risk`: `read`, `change`, `tell_me`, `ask` or `owner_only`.
* `input` (required): a JSON Schema object, at most 16 KB. StackShift checks the arguments against it before anything else.
* `money`: `amountField`, `currencyField` and an optional `limit` per currency. The action counts as a cost, and over the limit it is refused.
* `reachesPeople`: `true` if the action contacts people.
* `safe`: `undo` names the action that undoes this one.
* `output`: `trusted` or `untrusted`. Leave it out and the output counts as untrusted.

## Expected result

> [!TIP]
>
> StackShift creates or updates the agent from the file. What you see in the agent’s settings for its own actions comes from the file and is read-only there.

## Common failures

> [!WARNING]
>
> * agent sleepAfter must be between 5m and 1h, or never.
> * agent budget for one run is above the monthly budget: lower aiCreditsPerRun or raise aiCreditsPerMonth.
> * agent action input must be an object schema: every action needs `input` with `type: object`, at most 16 KB.
> * money amountField is not in its input: `amountField` and `currencyField` must both be properties of the action’s input.
> * An action can only be `safe` when its risk is `change` or `tell_me`, it moves no money, it reaches nobody and it names an undo action that is declared.
> * The file lists more than one agent. Put each agent in its own folder.

## Related guides

> [card] [Your agent’s own actions: risk, approvals and levels](https://docs.stackshift.cloud/ai-features/hosted-agents-actions.md)
>
> Declare the tools your agent has, give each a risk, and let StackShift apply the agent’s level, approvals and untrusted-text checks before they run.

> [card] [Events that wake your agent](https://docs.stackshift.cloud/ai-features/hosted-agents-events.md)
>
> Every email, agreement, schedule, webhook and approval reaches your agent as a signed event. The SDK checks it, drops repeats and runs your handler.

> [card] [Internet access and secrets for agents](https://docs.stackshift.cloud/ai-features/hosted-agents-internet.md)
>
> An agent reaches only StackShift and model access until you allow more. Its keys for other services stay secret, and some it never holds at all.


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