ShipSF Workshops - Mini-workers workshop with Notion

Highlights

• Notion workers provide an SDK and runtime that allow AI agents to deploy and execute custom code securely via the NTM CLI.

• Vercel's brokered credentials prevent agents from logging or stealing API tokens by injecting credentials into outgoing network headers just-in-time from a secure proxy.

• Worker tool schemas are automatically extracted by JSON stringifying module exports in a sandbox and validating their shape with Zod objects.

• Sandbox execution enforces a strict five-minute timeout limit to prevent runaway computations or malicious resource consumption.

• Agents avoid context window bloat by using progressive disclosure, initially listing only tool names and descriptions through the NTM CLI before loading full input schemas.

Timeline

1. 00:00 - 02:28

   Core architecture and capabilities of Notion workers

   Notion workers provide a dedicated environment for extending AI agents beyond standard Model Context Protocol limitations. Developers and agents can write local scripts that transition into deployed tools without managing underlying infrastructure or exposing raw credentials. This architecture allows internal databases and tools to interface securely with automation workflows.

   • Workers function as an SDK and runtime that extend Notion with custom code written by users or AI agents.
   • Three distinct worker capabilities include agent tools, external data syncs, and deterministic automations.
   • The NTM CLI abstracts away deployment infrastructure management and credential handling for agents.
2. 02:28 - 04:43

   Mitigating security risks with Vercel Sandbox

   Executing arbitrary code written by AI agents creates significant vulnerabilities regarding data access and resource fairness. Traditional credential sharing risks letting agents capture and misuse API keys. Partnering with Vercel Sandbox solves this by keeping credentials entirely outside the sandbox environment, using an external proxy to append tokens right as network requests go out.

   • Hosting arbitrary user code introduces risks such as crypto mining, denial-of-service attacks, and credential leakage.
   • Vercel's brokered credentials eliminate sandbox exposure by injecting API tokens directly into outgoing network request headers.
   • Proxied credential injection prevents AI agents from logging tokens into their context windows during code execution.
3. 08:35 - 16:20

   Code structure and schema extraction workflows

   Writing a worker requires defining specific module exports that describe the tool's interface and behavior. The system avoids manual manifest generation by letting the code describe itself through standard exports and Zod schemas. During deployment, sandboxes inspect these modules via standard output logging, validate their shapes, and register them as callable agent tools.

   • Worker code exports module keys containing tool names, descriptions, input schemas, and execution functions.
   • Sandboxes compile TypeScript source code from blob storage into tarball bundles before deployment.
   • Tool extraction uses JSON stringification on module exports to strip out execution logic and expose clean schemas to agents.
4. 16:20 - 21:06

   Execution sandboxing and state management

   Tool execution occurs within isolated, ephemeral sandbox environments initialized from cached snapshots for performance. Relevant outputs are wrapped in XML tags and parsed from standard output to filter out stray logs. While worker tools remain strictly stateless, agent computers support sequential bash commands and persistent file management by syncing state back to blob storage.

   • Fresh sandbox snapshots ensure that prior tool invocations do not contaminate the state of future runs.
   • Production environments enforce a strict five-minute execution cutoff to halt expensive or runaway computations.
   • Agent computers maintain persistent file states across sessions by backing up and streaming files via blob storage.
5. 21:06 - 28:43

   Context window optimization and error recovery

   Scaling the number of custom tools an agent can access requires careful memory management to avoid token limits. Progressive disclosure allows agents to inspect tool names first and query full schemas only when needed. When tool execution fails due to network instability or bad parameters, agents use error feedback to adjust inputs and retry operations successfully.

   • Progressive disclosure prevents context window bloat by displaying only tool names and descriptions initially.
   • Agents recover from flaky tool calls by processing error messages and self-correcting through their native memory systems.
   • NTM CLI deployment offers a simpler alternative to traditional cloud functions for agentic workflows.