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-sdkwithzod, or@openai/agentsfor TypeScript;anthropic,openai,claude-agent-sdkoropenai-agentsfor 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 itstype, 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
Related guides
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.