getstack

Python SDK for STACK — trust infrastructure for AI agents.

Install

pip install getstack

Quick start

Sign in once on your machine — the SDK reads credentials from ~/.stack/credentials.json automatically:

npx -y @getstackrun/cli auth login

from getstack import Stack

# Zero-arg constructor reads ~/.stack/credentials.json (OAuth refresh token).
# Falls back to STACK_API_KEY env var, then constructor api_key= for CI.
stack = Stack()

# 1. Register an agent (one-time)
agent = stack.agents.register("my-agent", accountability_mode="enforced")

# 2. In your agent runtime, switch to per-agent keypair mode
agent_stack = Stack(agent_id=agent.id)
# First run: generates an Ed25519 keypair locally + enrolls the public
# half via /v1/agents/<id>/enroll. Persisted at ~/.stack/agents/<id>.json
# (mode 0600). Every subsequent call signs a fresh 60-second JWT.

# 3. Run a mission with automatic checkpoints and checkout
with agent_stack.passports.mission(
    agent_id=agent.id,
    intent="Process invoices from Slack",
    services=["slack", "stripe"],
    checkpoint_interval="5m",
) as mission:
    mission.log("slack", "read_channel", "#invoices")
    mission.log("stripe", "create_invoice")
    # Checkpoints are submitted automatically on schedule
# Checkout is submitted automatically when the block exits

Authentication

Four sources, resolved in priority order:

# 1. Explicit auth strategy
stack = Stack.from_oauth(client_id="...", client_secret="", access_token="...", refresh_token="...")
stack = Stack.from_session(session_token="...")

# 2. agent_id (Phase 2 — recommended for production runtimes)
stack = Stack(agent_id="agt_xxx")

# 3. api_key (legacy sk_live_*; for CI without a browser)
stack = Stack(api_key="sk_live_...")
# or set STACK_API_KEY in the environment

# 4. ~/.stack/credentials.json (Phase 1 — `stack-cli auth login` writes it)
stack = Stack()

See /docs/security/stack-auth for the full auth model and /docs/security/agent-keys for the per-agent keypair story.

Continuous missions (24/7 agents)

for mission in stack.passports.continuous_mission(
    agent_id=agent.id,
    intent="Monitor Slack channels",
    services=["slack"],
    rotation_interval="4h",
    checkpoint_interval="5m",
):
    while not mission.should_rotate:
        event = wait_for_event()
        mission.log("slack", "read_message")
        process(event)
    # Passport rotates automatically at the boundary

Services

# Agents
stack.agents.register(name, description=None, accountability_mode="enforced")
stack.agents.get(agent_id)
stack.agents.list()
stack.agents.update(agent_id, **fields)
stack.agents.unblock(agent_id)

# Passports
stack.passports.issue(agent_id, intent=None, services=None, ...)
stack.passports.verify(token)
stack.passports.revoke(jti, reason=None)
stack.passports.checkpoint(jti, services_used, actions_count, ...)
stack.passports.checkout(jti, services_used, actions_count, ...)
stack.passports.report(jti)

# Credentials
stack.credentials.get(provider)
stack.credentials.get_by_connection(connection_id)

# Services
stack.services.list()
stack.services.connect_custom(name, credential, ...)
stack.services.verify(connection_id)
stack.services.disconnect(connection_id)

# Reviews
stack.reviews.list(status="flagged")
stack.reviews.decide(checkout_id, decision, notes=None, block_future=False)

# Drop-offs
stack.dropoffs.create(from_agent_id, to_agent_id, schema, ...)
stack.dropoffs.deposit(dropoff_id, data, agent_id)
stack.dropoffs.collect(dropoff_id, agent_id)

# Notifications
stack.notifications.list()
stack.notifications.create(channel_type, destination, ...)
stack.notifications.delete(channel_id)

# Audit
stack.audit.list(page=1, limit=50, action=None, agent_id=None)

Links

• Documentation
• Dashboard
• GitHub