---
title: "From Agent Folder to Shippable Agent: Five Checkpoints"
description: "An Agent SDK agent is a folder of instructions, tools, skills, and channels. This walkthrough follows five checkpoints from local validation to gateway-gated tool calls and replayable evals."
---

# From Agent Folder to Shippable Agent: Five Checkpoints

**Type:** [How to](https://yomu.fyi/visual-explainers/category/how-to.md)

![A five-step horizontal flow: author the agent folder, choose channels, validate locally, gate tool calls at an MCP gateway, then replay pull requests as fixtures for evals, ending at a ship gate band.](https://yomufyi.s3.us-east-1.amazonaws.com/visual-explainers/b0523607-eae1-44e7-8cc3-e9870e1690d0/image-67367c65-63ee-460f-bd27-d7bb5debb64c.webp)

> An Agent SDK agent is a folder of instructions, tools, skills, and channels. This walkthrough follows five checkpoints from local validation to gateway-gated tool calls and replayable evals.

## Explanation

The Agent SDK treats an agent as a folder of code: an instructions.md prompt, typed functions in tools/, loadable procedures in skills/, MCP server tools in mcp-connections/, and message handling in channels/. Shipping one is less about the model call than about the checkpoints around it: validate the structure locally before deploying, decide which channels may reach the agent, put a policy boundary in front of every tool call, and replay real pull requests as signed fixtures so evals can assert on tool calls and replies. Each checkpoint removes a class of failure that is expensive to debug once the agent is live.

## FAQ

### How do I test an agent without running it against live traffic?

The Agent SDK's replay command converts real pull requests into signed fixtures, so evals can assert on tool calls and replies without touching live repositories. A separate Databricks benchmark found declarative pipelines that validate structure before execution used roughly 34x less cluster compute than procedural ones, which is the same habit: catch structural errors before you spend runtime.

### Where should tool permissions for an agent actually be enforced?

At the gateway, not in the prompt. A shared MCP gateway needs a policy boundary beyond authentication: validate OIDC or JWT credentials, authorize per tool against identity-provider role claims, and add network policy plus rate limits. Those controls map to OWASP risks for agentic applications including excessive agency, unbounded consumption, tool misuse, and identity abuse.

### How narrow should an agent's tool and channel surface be?

Only as wide as a named requirement. The Agent SDK forces you to declare tools/, skills/, mcp-connections/, and channels/ explicitly, and Supabase scopes personal access tokens to one resource, one permission set, and an expiry so the blast radius is reviewable before use. Fly.io's MCP server goes further, authorizing per app and organization with no API token.

**Tags:** [Agent SDK](https://yomu.fyi/topic/agent-sdk.md), [AI Agents](https://yomu.fyi/topic/ai-agents.md), [Evaluation](https://yomu.fyi/topic/evaluation.md), [Guardrails](https://yomu.fyi/topic/guardrails.md), [MCP](https://yomu.fyi/topic/mcp.md), [Tool Calling](https://yomu.fyi/topic/tool-calling.md)

## Related reading

### [Scope your Personal Access Tokens](https://yomu.fyi/post/scope-your-personal-access-tokens.md)
- Company: [Supabase](https://yomu.fyi/company/supabase.md)
- Author: hieu, kemal\_y, gildas\_garcia, wenbo
- Published: Oct 26, 2026
- Type: Announcement

Supabase now scopes Personal Access Tokens to specific resources and permissions, limiting what each token can do. Announced at Supabase Select on October 2 after becoming generally available on September 28, the feature lets you choose resources such as a single project, permissions such as read-only database access, and an expiration date up to one year. The token’s scope is fixed at creation, and its effective permissions are bounded by the user’s own role; losing access revokes the token’s ability until restored. A review screen shows the blast radius with a risk banner, and scoped tokens start with the prefix sbp\_fc. Existing full-access tokens remain unaffected and carry a Legacy badge, while the Dashboard now creates scoped tokens by default, with nearly nine out of ten new tokens scoped.


### [Give Deep Agents a Searchable Filesystem on MongoDB Atlas](https://yomu.fyi/post/give-deep-agents-a-searchable-filesystem-on-mongodb-atlas.md)
- Company: [MongoDB](https://yomu.fyi/company/mongodb.md)
- Published: Oct 26, 2026
- Type: Tutorial

A multi-agent pipeline with a coordinator, three search sub-agents, and a reconciler searches a 2,900-page, 45-file federal docket on room air cleaner efficiency standards from the U.S. Department of Energy using a virtual filesystem on MongoDB Atlas. The VFS backend routes search operations like glob and grep to Atlas Search and Vector Search, where $rankFusion combines full-text and vector results natively in a single database-side query, while S3 holds the original bytes as the source of truth. A polling watcher keeps the Atlas index aligned with S3 bucket changes. Agents work incrementally through ls, glob, grep, read, write, and edit operations without loading the entire corpus into their context window. The pipeline can be interrupted and resumes from the last completed stage using saved run state, costing $2 to $5 in API calls over about 45 minutes.


### [Built for Agents: The Case for Spark Declarative Pipelines](https://yomu.fyi/post/built-for-agents-the-case-for-spark-declarative-pipelines.md)
- Company: [Databricks](https://yomu.fyi/company/databricks.md)
- Author: Lisa Cao, Sudhanva Huruli
- Published: Oct 23, 2026
- Type: Benchmark

AI agents now create over 70% of Spark data pipelines on Databricks, making cheap iteration and readable code critical. A benchmark comparing procedural PySpark with declarative pipelines tested 22 tasks across 12 datasets each, totaling 528 builds using Opus 4.8 for agent coding and an automated grader. Declarative pipelines enable dry-run validation that catches structural errors before execution, reducing cluster compute time by roughly 34x compared to procedural pipelines, which used 596 executor-seconds versus 17. Declarative code was about half the size (median 64 vs 131 lines) with less variability, while silent error rates were similar within about 15%. The declarative approach trades 2.3x higher LLM token costs ($0.50 vs $0.26 median) for eliminating wasted cluster time, a trade-off that improves as data volumes grow because compute waste scales while token costs are fixed.


### [Locking down MCP at the gateway](https://yomu.fyi/post/locking-down-mcp-at-the-gateway.md)
- Company: [Red Hat](https://yomu.fyi/company/red-hat.md)
- Author: David Martin, Jason Madigan
- Published: Oct 23, 2026
- Type: Tutorial

Model Context Protocol (MCP) allows an agent to use tools across enterprise systems, but a shared MCP gateway requires a policy boundary beyond authentication. The article describes using Red Hat Connectivity Link (RHCL) AuthPolicy to validate OIDC or JWT credentials and then authorize per-tool access based on roles in the identity provider claims. NetworkPolicy controls which workloads can communicate with the gateway and MCP servers, while RateLimitPolicy limits request volume. Gateway isolation can be achieved with separate gateway instances or a shared gateway with isolated listeners, each with its own MCPGatewayExtension. These controls map to OWASP risks for LLM and agentic applications, including excessive agency, unbounded consumption, tool misuse, and identity abuse.


### [Feng Shui for Robots: The Fly MCP Server](https://yomu.fyi/post/feng-shui-for-robots-the-fly-mcp-server.md)
- Company: [Fly.io](https://yomu.fyi/company/fly-io.md)
- Published: Oct 23, 2026
- Type: Announcement

In October 2023 AI agents created 0.1% of databases on Neon; by October 2025 they created 80%, and at Fly.io agents have overtaken humans as the most common customer species. Fly.io built mcp.fly.io, an MCP server that connects agents to Sprites for sandboxed development and to Fly Machines for production, providing a path from prototype to scalable deployment. Sprites are real Linux machines with persistent disk, service management, HTTPS URLs, and filesystem checkpoints that allow agents to install packages, run servers, and roll back after failures, and they sleep when idle. When a project needs always-on availability, the agent can migrate it from a Sprite to a Fly Machine using the same MCP server, creating the Machine, volume, and secrets in the same conversation. The MCP server is authorized per app and organization with no API token, and Fly.io is investigating adding MPG skills for database management.


### [Agent SDK](https://yomu.fyi/post/agent-sdk.md)
- Company: [Cursor](https://yomu.fyi/company/cursor.md)
- Published: Oct 20, 2026
- Type: Announcement

The Agent SDK is now generally available, letting developers define an agent as a folder of code using an instructions.md file as the prompt. The project structure includes tools/ for typed functions, skills/ for loadable procedures, mcp-connections/ for MCP server tools, and channels/ for message handling. The CLI provides commands for initialization, local development with a playground, validation, and deployment to Cursor or self-managed infrastructure. When deployed, secrets and integrations are managed from a dashboard while logs, evals, and the playground remain available, and agents can receive and respond to messages through GitHub, GitLab, Bitbucket, Slack, webhooks, and cron schedules with session persistence. Evals allow asserting on tool calls and replies, and the agent-sdk github replay command converts real pull requests into signed fixtures for offline testing.
