# 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](/policies/overview/), resolves credentials (see [Managed Authentication](/guides/managed-authentication/)), applies execution rules defined in [`manifest.json`](/configuration/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. ```text 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 Agent ``` Each 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`. ```text tooling.json ↓ github.issue.create ↓ Trusted Tool ``` If 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](/policies/overview/)). ```text 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: ```text Sandbox Mode │ ▼ sandbox_endpoint ``` or ```text Production Mode │ ▼ production_endpoint ``` The 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](/guides/managed-authentication/)). Credentials are resolved in priority order. ```text Environment Variables │ ▼ Managed Credentials │ ▼ Project .env ``` The 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`](/configuration/manifest-json/). Execution policies control runtime behavior such as: - Retry strategy (see [Retries](/guides/retries/)) - Timeout configuration - Idempotency (see [Idempotency](/guides/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](/guides/retries/)). --- ## Step 7 - Execute the API Request Once every validation step succeeds, Swytchcode sends the request directly to the provider. ```text Swytchcode ↓ GitHub API or Stripe API or Slack API ``` Swytchcode 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](/guides/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. ```text 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](/configuration/tooling-json/)) | | `policies.json` | Evaluates runtime rules before execution. (ref: [policies.json](/configuration/policy-json/)) | | `manifest.json` | Configures endpoints, authentication, retries, timeouts, and execution behavior. (ref: [manifest.json](/configuration/manifest-json/)) | | `credentials.db` | Securely stores managed provider credentials. (see: [Managed Authentication](/guides/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. ```text 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 1 ``` Failing 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](/cli/exec/#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): ```bash swy auth workspace swy auth workspace # equivalent, shorter form swy auth link swy auth link ``` 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](https://docs.swytchcode.com/guides/authentication/) - Learn how Swytchcode authenticates your account and provider integrations. - [Managed Authentication](https://docs.swytchcode.com/guides/managed-authentication/) - Understand how provider credentials are securely stored and resolved during execution. - [Policies & Guardrails](https://docs.swytchcode.com/policies/overview/) - Discover how policies validate and protect every tool execution before it reaches an API. - [Retries](https://docs.swytchcode.com/guides/retries/) - Learn how Swytchcode automatically retries transient failures using configurable execution policies. - [Idempotency](https://docs.swytchcode.com/guides/idempotency/) - Prevent duplicate operations when retrying mutating API requests. - [manifest.json](https://docs.swytchcode.com/configuration/manifest-json/) - Configure endpoints, retries, timeouts, concurrency, and idempotency for each integration. - [tooling.json](https://docs.swytchcode.com/configuration/tooling-json/) - Define the trusted methods and workflows that your project is allowed to execute. - [policies.json](https://docs.swytchcode.com/configuration/policy-json/) - Explore the complete schema for defining custom runtime policy rules.