Execution Pipeline
Every tool execution in Swytchcode follows the same deterministic pipeline.
Before an API request leaves your machine, Swytchcode validates the request, evaluates policies, resolves credentials (see Managed Authentication), applies execution rules defined in manifest.json, and only then sends the request to the provider.
This ensures that every API call is trusted, authenticated, policy-compliant, and production-ready.
The Execution Flow
Every execution follows the same sequence.
AI Agent / SDK / CLI │ ▼ Resolve Tool (tooling.json) │ ▼ Validate Inputs │ ▼ Evaluate Policies (policies.json) │ │ Allowed Blocked │ │ ▼ ▼ Resolve Base URL Exit (Policy Error, code 4) (manifest.json) │ ▼ Resolve Credentials │ ▼ Apply Execution Policy (Retries • Timeouts • Idempotency) │ ▼ Execute HTTP Request │ ▼ Normalize API Response │ ▼ Return to AgentEach stage performs one specific responsibility.
If any stage fails, execution stops immediately and returns a descriptive error.
Step 1 - Resolve Tool
The execution begins by identifying the requested tool.
Swytchcode looks up the requested method or workflow inside tooling.json.
tooling.json
↓
github.issue.create
↓
Trusted ToolIf the requested tool is not present in tooling.json, execution stops immediately.
This guarantees that AI agents can only execute tools that have been explicitly enabled for the project.
Step 2 - Validate Inputs
After resolving the tool, Swytchcode validates the incoming request.
Validation includes:
- Required fields
- Supported input types
- Missing parameters
- Invalid values
Requests that do not satisfy the tool’s input contract are rejected before any external API call is made.
Step 3 - Evaluate Policies
Once the request is valid, Swytchcode evaluates every matching policy defined in policies.json (learn more: Policies & Guardrails).
Incoming Request
↓
Matching Policies
↓
Evaluate Conditions
↓
Pass ✓
or
Block ✕Policies may prevent execution for reasons such as:
- Organization rules
- Spending limits
- Production restrictions
- Security policies
- Time-based rules
If a policy blocks execution, the request ends immediately without contacting the provider.
Step 4 - Resolve the Endpoint
After the request passes policy validation, Swytchcode determines where the request should be sent.
The runtime reads the integration configuration from manifest.json.
Depending on the project’s execution mode:
Sandbox Mode │ ▼sandbox_endpointor
Production Mode │ ▼production_endpointThe selected base URL is combined with the method endpoint to create the final request URL.
Step 5 - Resolve Credentials
Before sending the request, Swytchcode resolves the credentials required by the provider (learn more: Managed Authentication).
Credentials are resolved in priority order.
Environment Variables │ ▼Managed Credentials │ ▼Project .envThe first valid credential found is automatically used.
This process happens transparently without requiring manual authentication logic inside your application.
Step 6 - Apply Execution Policy
Before the HTTP request is sent, Swytchcode applies the execution policy defined in manifest.json.
Execution policies control runtime behavior such as:
- Retry strategy (see Retries)
- Timeout configuration
- Idempotency (see Idempotency)
- Concurrency limits
- Maximum response size
For example, if a provider temporarily returns a 503 Service Unavailable response, Swytchcode can automatically retry the request according to the configured retry policy (learn more: Retries).
Step 7 - Execute the API Request
Once every validation step succeeds, Swytchcode sends the request directly to the provider.
Swytchcode
↓
GitHub API
or
Stripe API
or
Slack APISwytchcode acts as the execution runtime.
It does not proxy or permanently store your API traffic.
Requests are authenticated using the resolved provider credentials (see Managed Authentication) and sent directly to the configured provider endpoint.
Step 8 - Normalize the Response
After receiving the provider response, Swytchcode normalizes the output before returning it to your application.
This includes:
- Parsing structured responses
- Standardizing errors
- Returning consistent output
- Formatting execution results
This allows applications to consume provider responses through a predictable interface.
How the Configuration Files Work Together
Three configuration files drive every execution.
tooling.json What can execute? │ ┌──────────────┼──────────────┐ │ │ │ ▼ ▼ ▼ manifest.json credentials.db policies.json How to execute Who executes Should it execute?Each file has a dedicated responsibility.
| File | Responsibility |
|---|---|
tooling.json | Defines trusted methods and workflows available to the project. (ref: tooling.json) |
policies.json | Evaluates runtime rules before execution. (ref: policies.json) |
manifest.json | Configures endpoints, authentication, retries, timeouts, and execution behavior. (ref: manifest.json) |
credentials.db | Securely stores managed provider credentials. (see: Managed Authentication) |
Together, these files provide a predictable, secure, and configurable execution model.
Fail Fast by Design
Every stage in the execution pipeline validates a specific part of the request.
If any validation fails, execution stops immediately.
Resolve Tool │ ✗ Unknown Tool → exit code 5
Validate Inputs │ ✗ Invalid Request → exit code 2
Evaluate Policies │ ✗ Policy Violation → exit code 4
Resolve Credentials │ ✗ Missing Authentication → exit code 3
Execute Request │ ✗ Provider Error → exit code 1Failing early prevents invalid or unsafe requests from reaching external services. These are the same exit codes swy exec returns to the shell - see Exit Codes for the full table, which is what you’d check in a CI script or agent harness to distinguish “the tool doesn’t exist” from “a policy blocked it” from “the provider itself failed.”
Workspace linking
A workspace is the Swytchcode account/organization a project is billed and audited under. Most projects use whichever workspace you’re signed into by default, but some setups (multiple teams, multiple clients) need to pin a project to a specific one.
Use swy auth workspace to show or change which workspace the current project uses (link is a shorter alias for the same subcommand):
swy auth workspaceswy auth workspace <alias-or-uuid>
# equivalent, shorter formswy auth linkswy auth link <alias-or-uuid>The selected workspace is stored in .swytchcode/workspace.json and is local to the machine.
Why This Pipeline Matters
The execution pipeline provides several important guarantees:
- Only trusted tools can execute.
- Every request is validated before execution.
- Organization policies are enforced consistently.
- Credentials are resolved securely.
- Retry and timeout behavior is standardized.
- Every API call follows the same execution path.
Because every request passes through the same pipeline, developers can confidently build AI agents that behave consistently across development and production environments.
To learn more about each stage of the execution pipeline, continue with:
Related Concepts
Authentication
Learn how Swytchcode authenticates your account and provider integrations.
Managed Authentication
Understand how provider credentials are securely stored and resolved during execution.
Policies & Guardrails
Discover how policies validate and protect every tool execution before it reaches an API.
Retries
Learn how Swytchcode automatically retries transient failures using configurable execution policies.
Idempotency
Prevent duplicate operations when retrying mutating API requests.
manifest.json
Configure endpoints, retries, timeouts, concurrency, and idempotency for each integration.
tooling.json
Define the trusted methods and workflows that your project is allowed to execute.
policies.json
Explore the complete schema for defining custom runtime policy rules.