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

Goal

Write an agent that StackShift can run, govern and stop, in TypeScript or Python.

Prerequisites

  • Node 20 or newer for TypeScript, or Python 3.9 or newer.
  • The official packages you want to use: @anthropic-ai/sdk, openai, @anthropic-ai/claude-agent-sdk with zod, or @openai/agents for TypeScript; anthropic, openai, claude-agent-sdk or openai-agents for Python. They are optional.

Workflow

1
Install @stackshift-cloud/agent (npm install) or stackshift-agent (pip install).
2
Register handlers with agent.on(event, …) and wrap each declared action with agent.action(key, …).
3
End the file with agent.start(). It listens on PORT, 8080 unless you set it, and answers POST /stackshift/events.
4
Declare each action and each StackShift action you use in the agent block of stackshift.yaml.
5
Deploy. StackShift sets STACKSHIFT_API_URL, STACKSHIFT_AGENT_ID, STACKSHIFT_AGENT_HANDLE, STACKSHIFT_EVENT_KEY and PORT for the agent.

A first agent

The handler gets the event with its type, id, at, data, untrusted and run id. Each event is checked against STACKSHIFT_EVENT_KEY before any handler runs. A repeated event id is dropped. A handler that throws ends the run failed, a run that saved an action for approval ends waiting, and anything else ends done.

StackShift calls, inbox, agreements and state

agent.platform.call(key, args) proposes a StackShift action through the agent’s connection and waits up to 55 seconds for it to settle. agent.platform.inspect(key, args) runs a read. The agent can use only the actions in its platform: list. agent.inbox has send, reply, info and id. agent.agreements has list, inspect, limits, verify, wait, propose, respond, cancel and countReply (count_reply in Python); it works when agreements are on for the agent’s inbox. agent.state keeps values and locks that survive sleep.

Models and the internet

agent.anthropic() and agent.openai() return the official clients, pointed at StackShift and signed in with the run token (async_anthropic and async_openai in Python). agent.fetch reaches the addresses you allow, adding any key you saved to send on the way out. agent.untrusted(text, source) marks text your code fetched itself.

Claude Agent SDK and OpenAI Agents SDK

The adapters turn your declared actions into tools for those SDKs, with the approval step built in. A refusal or a wait comes back to the model as text, not as a crash. Call them while handling an event.

Manage agents from outside

The StackShift SDKs manage agents from your own scripts: stackshift.hostedAgents in @stackshift-cloud/sdk and stackshift.hosted_agents in the Python stackshift package. They have list, get, create, deploy, rollback, stop, start, delete, runs, spend and logs, plus secrets.set and unset and budget.set.

Expected result

Your agent receives signed events once each, asks StackShift before its declared actions, and calls models and StackShift with the run token the SDK keeps for it.

Common failures

  • start fails with “STACKSHIFT_EVENT_KEY is not set”: the agent is not running on StackShift. Set the variable to test locally.
  • Calls to StackShift fail with “The agent has no run token yet”: the SDK gets its token from each event, so call StackShift while handling one.
  • An action fails with “Actions run while the agent handles an event”: call wrapped actions from a handler, not at start-up.
  • agent.anthropic() says to install the package: add @anthropic-ai/sdk or anthropic.

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.

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.