The agent block in stackshift.yaml

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

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

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

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

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

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

An example

stackshift.yaml

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

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

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.

Your agent’s own actions: risk, approvals and levels

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.

Events that wake your agent

Every email, agreement, schedule, webhook and approval reaches your agent as a signed event. The SDK checks it, drops repeats and runs your handler.

Internet access and secrets for agents

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.

​Goal

​Prerequisites

​Workflow

​An example

​Fields of the agent block

​Fields of an action

​Expected result

​Common failures

​Related guides

Your agent’s own actions: risk, approvals and levels

Events that wake your agent

Internet access and secrets for agents

Goal

Prerequisites

Workflow

An example

Fields of the agent block

Fields of an action

Expected result

Common failures

Related guides