diff --git a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index b45b694f7..e5da7e5f3 100644 --- a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -8,24 +8,28 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -### Turn production errors into draft PRs with Cloud Agents + TypeScript SDK +## Turn production errors into draft pull requests - +In this demo, Ben builds a small TypeScript "Sentry monitor" service that listens for specific Sentry alerts (like a Go nil pointer dereference) and starts a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and passes it to an agent run inside a Warp environment so the agent can inspect the repo and propose a fix. -:::note -Example repository: [**Sentry monitor example repository**](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor) -::: + -In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. +The code is in the [Sentry monitor example repository](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor). -To route the alert through a factory's named agents and workflow instead, use [factory endpoints](/factories/factory-api/) to dispatch the request. This example remains useful for custom standalone cloud-agent intake. +To route the alert through a factory's named agents and workflow instead, dispatch the request with [factory endpoints](/factories/factory-api/). This example is still the pattern for custom standalone cloud-agent intake. -He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. +The demo also covers the run lifecycle basics in the TypeScript SDK (running an agent, then polling run state to fetch a session link for debugging) and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. -**What Ben covers** +## What the demo covers -* Using Warp's TypeScript SDK to trigger agent runs and retrieve run details. -* Handling run lifecycle states (queued → running) to reliably fetch a session link. -* Running agents inside a Warp Environment so they can investigate real code, run tests, and validate fixes. +* Using Warp's TypeScript SDK to start agent runs and retrieve run details. +* Handling run lifecycle states, from queued to running, to reliably fetch a session link. +* Running agents inside a Warp environment so they can investigate real code, run tests, and validate fixes. * Building a lightweight Sentry webhook server that filters, validates, and routes only the right errors to an agent. -* Creating a workflow that results in draft PRs for human review, instead of silent autonomous changes. +* Creating a workflow that results in draft PRs for human review instead of silent autonomous changes. + +## Related pages + +* [Agent and run endpoints](/factories/api-and-sdk/) - The endpoints and SDKs the demo builds on. +* [{VARS.WARP_PLATFORM_API} quickstart](/factories/api-and-sdk/quickstart/) - Create and inspect your first run. +* [Triggering automations with custom webhooks](/factories/webhooks/) - Route Sentry and other webhook deliveries into a factory without writing a server. diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index 49e560679..007c60c0d 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -10,47 +10,33 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Agent & run endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](/factories/factory-api/). +The agent and run endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](/factories/factory-api/). -:::note -Some examples use `oz` commands, such as `oz environment list`, from the {VARS.WARP_AGENT_CLI}. Existing commands remain supported during the transition. -::: +## Use the agent and run endpoints -## Use Agent & run endpoints +The agent and run endpoints let you create and inspect [cloud agent](/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without the Warp desktop app. With the API you can: -Agent & run endpoints let you create and inspect [cloud agent](/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without requiring the Warp desktop app. +* Run an agent by submitting a prompt plus optional configuration, such as the model, environment, MCP servers, and base prompt. +* Monitor execution by listing runs and tracking state transitions over time, from queued through in progress to succeeded or failed. +* Inspect results and provenance by fetching a run's full details, including the original prompt, source and creator metadata, session link, and resolved agent configuration. -**With the API you can:** +For endpoint details, use the [{VARS.WARP_PLATFORM_API} reference](/api). For SDK schemas, use the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repositories. -* Run an agent by submitting a prompt plus optional config (model, environment, MCP servers, base prompt, etc.) -* Monitor execution by listing runs and tracking state transitions over time (queued → in progress → succeeded/failed) -* Inspect results and provenance by fetching a run's full details, including the original prompt, source/creator metadata, session link, and resolved agent configuration - -For endpoint details, use the [**{VARS.WARP_PLATFORM_API} reference**](/api). For SDK schemas, use the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repositories. - -To send work to a [Warp factory](/factories/), use [factory endpoints](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/runs` with a foreman's `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched. +To send work to a [factory](/factories/), use [factory endpoints](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/runs` with a foreman's `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched. ## Choose the SDK or raw REST Warp provides the official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk). Both SDKs wrap the {VARS.WARP_PLATFORM_API} with: -* **Typed requests and responses** (editor autocomplete, fewer schema mistakes) -* **Built-in retries and timeouts** (with per-request overrides) -* [**Consistent error types**](/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes -* **Helpers for raw responses** when you need headers/status or custom parsing +* **Typed requests and responses** - Editor autocomplete and fewer schema mistakes. +* **Built-in retries and timeouts** - With per-request overrides. +* **Consistent error types** - [Errors](/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes. +* **Helpers for raw responses** - For when you need headers, the status code, or custom parsing. -If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. +Use the SDK for strong typing, standardized error handling, and concurrency patterns. Use raw REST for minimal dependencies or full control over your HTTP client; the SDKs can also call undocumented endpoints when needed. -**SDK vs raw REST** - -* Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns. -* Use raw REST when you want minimal dependencies or full control over your HTTP client (the SDKs also support calling undocumented endpoints when needed). - - ---- - ## API base URL All endpoints are served over HTTPS: @@ -71,21 +57,21 @@ An agent run represents a single execution of a cloud agent, created with a prom * Optional session information (`session_id`, `session_link`) * Optional resolved configuration (`agent_config`) -See the [**{VARS.WARP_PLATFORM_API} reference**](/api) for details on how runs are created and listed. +See the [{VARS.WARP_PLATFORM_API} reference](/api) for details on how runs are created and listed. ### Agent configuration -You can influence how an agent runs using AmbientAgentConfig, including: +The request's `AmbientAgentConfig` object shapes how an agent runs: -* `name` — a human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is automatically set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent — for example, grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name. -* `model_id` for LLM selection -* `base_prompt` to shape behavior -* `environment_id` to choose a `CloudEnvironment` -* `worker_host` to run a standalone cloud agent on a [self-hosted worker](/factories/self-hosting/) -* `skill_spec` to use a [skill](/agents/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`) -* `mcp_servers` to enable specific tools via MCP +* `name` - A human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent, such as grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name. +* `model_id` - The model to run. +* `base_prompt` - Instructions that shape the agent's behavior. +* `environment_id` - The `CloudEnvironment` to run in. +* `worker_host` - A [self-hosted worker](/factories/self-hosting/) to run a standalone cloud agent on. +* `skill_spec` - A [skill](/agents/capabilities/skills/) to use as the base prompt, in `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md` form. +* `mcp_servers` - MCP servers whose tools the agent can use. -See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. +See the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) or [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. #### Skill actions in conversation data @@ -114,8 +100,6 @@ The catalog helps group usage across conversations; it isn't an availability man For example, `oz-platform`, `factory-files`, and `factory-mcp` are Warp-provided. `factory-mcp` appears only where Factory MCP is available, `tui-migrate-setup` is specific to the Warp Agent CLI, and connected integrations can add bundled IDs that aren't listed here. ---- - ## Route a run to a self-hosted worker Set `worker_host` in the request configuration to select a connected self-hosted worker. Omit it, or set it to `warp`, to use Warp-hosted workers. @@ -133,28 +117,14 @@ Replace `WORKER_HOST` with the ID of a connected worker. For factory work, set ` ## Key endpoints -Agent & run endpoints include: - -* `POST /agent/runs` - - Create a new agent run with a prompt and optional config and title. Returns run\_id and initial state. -* `GET /agent/runs` - - List runs with pagination and filters for state, config\_name, model\_id, creator, source, and creation time. -* `GET /agent/runs/{runId}` - - Fetch full details for a single run, including session link and resolved configuration. -* `POST /agent/runs/{runId}/followups` - - Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use. -* `POST /agent/runs/{runId}/cancel` - - Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run. +* `POST /agent/runs` - Create a new agent run with a prompt and optional config and title. Returns the `run_id` and initial state. +* `GET /agent/runs` - List runs with pagination and filters for state, `config_name`, `model_id`, creator, source, and creation time. +* `GET /agent/runs/{runId}` - Fetch full details for a single run, including the session link and resolved configuration. +* `POST /agent/runs/{runId}/followups` - Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use. +* `POST /agent/runs/{runId}/cancel` - Cancel a run that is queued or in progress. Returns the ID of the cancelled run. All endpoint semantics, query parameters, and [error codes](/factories/api-and-sdk/troubleshooting/errors/) are documented in the [{VARS.WARP_PLATFORM_API} reference](/api). ---- - ## Models The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include: @@ -173,17 +143,15 @@ The API shares a set of reusable models across endpoints. Detailed JSON schemas, * `MCPServerConfig` * `Error` ---- - ## SDKs ### Python SDK The Python SDK is the recommended way to call the API from Python services and scripts. It provides: -* Sync + async clients -* Typed request/response models -* Configurable retries/timeouts and structured errors +* Sync and async clients +* Typed request and response models +* Configurable retries and timeouts, and structured errors Install the package from PyPI: @@ -191,15 +159,15 @@ Install the package from PyPI: pip install warp-platform-sdk ``` -Import `WarpClient` from `warp_platform_sdk`. See the [**Python SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-python) for the full API reference and up-to-date examples. +Import `WarpClient` from `warp_platform_sdk`. See the [Python SDK GitHub repo](https://github.com/warpdotdev/oz-sdk-python) for the full API reference and up-to-date examples. ### TypeScript SDK -The TypeScript SDK is the recommended way to call the API from Node.js services and modern TS/JS runtimes. It provides: +The TypeScript SDK is the recommended way to call the API from Node.js services and modern TypeScript and JavaScript runtimes. It provides: -* Fully typed params/responses -* First-class error handling, retries/timeouts -* Support across common runtimes where fetch is available or polyfilled +* Fully typed params and responses +* First-class error handling, retries, and timeouts +* Support across common runtimes where `fetch` is available or polyfilled Install the package from npm: @@ -207,4 +175,11 @@ Install the package from npm: npm install @warp-dot-dev/warp-platform-sdk ``` -Import `WarpClient` from `@warp-dot-dev/warp-platform-sdk`. See the [**TypeScript SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-typescript) for the full API reference and up-to-date examples. +Import `WarpClient` from `@warp-dot-dev/warp-platform-sdk`. See the [TypeScript SDK GitHub repo](https://github.com/warpdotdev/oz-sdk-typescript) for the full API reference and up-to-date examples. + +## Related pages + +* [Factory endpoints](/factories/factory-api/) - Find a factory and send it work by UID. +* [{VARS.WARP_PLATFORM_API} quickstart](/factories/api-and-sdk/quickstart/) - Create and inspect your first run. +* [API errors](/factories/api-and-sdk/troubleshooting/errors/) - Every error code, its HTTP status, and how to resolve it. +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate parent and child runs through the same API. diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx index cf8d579b2..4d39e0e65 100644 --- a/src/content/docs/factories/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -2,39 +2,36 @@ topic: factories title: "{{WARP_PLATFORM_API}} quickstart" description: >- - Create and monitor your first cloud agent run via the {{WARP_PLATFORM_API}} in ~5 - minutes. + Create and monitor your first cloud agent run with the {{WARP_PLATFORM_API}} in + about five minutes. sidebar: label: "Quickstart" --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.WARP_PLATFORM_API} lets you run and manage cloud agents from CI/CD pipelines, backend services, scripts, or custom tooling without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. +Create your first cloud agent run with the {VARS.WARP_PLATFORM_API} and check its status, in about five minutes. The API runs and manages cloud agents from CI pipelines, backend services, scripts, or custom tooling without the Warp desktop app. To dispatch work through a factory's named agents and workflow, use [factory endpoints](/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run those endpoints create. -Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: - +This short demo shows how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team. ---- + ## Prerequisites * **A Warp API key** - Create one in the {VARS.WEB_APP} and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/agents/cli/oz-cli/api-keys/) for the full flow. * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) first. ---- - ## 1. Set your API key -Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the `WARP_API_KEY` environment variable. +Export your API key so every command in this quickstart can authenticate through the `WARP_API_KEY` environment variable. ```bash -export WARP_API_KEY="wk-..." +export WARP_API_KEY="YOUR_API_KEY" ``` -Replace `wk-...` with the key you created earlier. +Replace `YOUR_API_KEY` with the key you created earlier. Keys start with `wk-`. ## 2. Create your first run @@ -47,25 +44,25 @@ curl -X POST https://app.warp.dev/api/v1/agent/runs \ -d '{ "prompt": "Scan the repo for outdated dependencies and summarize the findings.", "config": { - "environment_id": "" + "environment_id": "ENV_ID" } }' ``` -Replace `` with your environment ID. Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. +Replace `ENV_ID` with your environment ID. Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. :::note -Prefer typed requests? The official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) wrap the same API with typed models, retries, and error handling. +The official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) wrap the same API with typed models, retries, and error handling. ::: -The API returns a `run_id` immediately. The agent starts asynchronously — you can check its status at any time using the run ID. +The API returns a `run_id` immediately. The agent starts asynchronously, and you can check its status at any time with the run ID. ## 3. Check run status -Fetch the current state of the run with the following command. Replace `` with the `run_id` from step 2. +Fetch the current state of the run. Replace `RUN_ID` with the `run_id` from step 2. ```bash -curl "https://app.warp.dev/api/v1/agent/runs/" \ +curl "https://app.warp.dev/api/v1/agent/runs/RUN_ID" \ -H "Authorization: Bearer $WARP_API_KEY" ``` @@ -76,7 +73,7 @@ The `state` has the following possible values: * `SUCCEEDED` - The run completed successfully. * `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code. -These are the most common states. See the [Agent & run endpoints](/factories/api-and-sdk/) and [{VARS.WARP_PLATFORM_API} reference](/api) for all possible values. +These are the most common states. See the [agent and run endpoints](/factories/api-and-sdk/) and the [{VARS.WARP_PLATFORM_API} reference](/api) for all possible values. To list all recent runs: @@ -87,15 +84,15 @@ curl "https://app.warp.dev/api/v1/agent/runs" \ ## 4. View the results -Once the run reaches `SUCCEEDED`, the response includes a `session_link` — a direct URL to the full run transcript, including commands executed, files changed, and agent output. +Once the run reaches `SUCCEEDED`, the response includes a `session_link`, a direct URL to the full run transcript, including commands executed, files changed, and agent output. You can also view and manage all runs in the {VARS.DASHBOARD}. ---- - ## Next steps -* **Read the endpoint guide** - [Agent & run endpoints](/factories/api-and-sdk/) documents the configuration and run lifecycle, while the [{VARS.WARP_PLATFORM_API} reference](/api) lists all parameters, query filters, and response schemas. -* **Explore the SDKs** - [`warp-platform-sdk` for Python](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` for TypeScript](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) include typed request/response models, retries, and error handling. -* **See a real-world example** - [Demo: Sentry monitoring with SDK](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. -* **Schedule and automate** - See [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear. +You created a run from the command line and read its state and transcript back. + +* [Agent and run endpoints](/factories/api-and-sdk/) - The configuration options and run lifecycle, with the [{VARS.WARP_PLATFORM_API} reference](/api) for every parameter, query filter, and response schema. +* [`warp-platform-sdk` for Python](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` for TypeScript](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) - Typed request and response models, retries, and error handling. +* [Sentry monitoring demo](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) - A webhook handler that starts agents from production errors. +* [Scheduled agents quickstart](/platform/triggers/scheduled-agents-quickstart/) and [integrations quickstart](/platform/integrations/quickstart/) - Run agents on a schedule, or start them from Slack or Linear. diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index ce324b322..327fb379d 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -12,14 +12,14 @@ The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent ru ## Choose an API surface -* **[Factory endpoints](/factories/factory-api/)** - Find a factory and send work to it by UID from your application or service. -* **[Agent & run endpoints](/factories/api-and-sdk/)** - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. -* **[{VARS.WARP_PLATFORM_API} reference](/api)** - Look up the full HTTP schema, parameters, and responses. -* **[Python SDK](https://pypi.org/project/warp-platform-sdk/)** - Install `warp-platform-sdk` to make typed requests from Python. -* **[TypeScript SDK](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk)** - Install `@warp-dot-dev/warp-platform-sdk` to make typed requests from TypeScript. -* **[API errors](/factories/api-and-sdk/troubleshooting/errors/)** - Resolve error responses by HTTP status and machine-readable code. -* **[Factory MCP](/factories/factory-mcp/)** - Exchange work between a factory and a connected coding agent or MCP client. -* **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. +* [Factory endpoints](/factories/factory-api/) - Find a factory and send work to it by UID from your application or service. +* [Agent and run endpoints](/factories/api-and-sdk/) - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. +* [{VARS.WARP_PLATFORM_API} reference](/api) - Look up the full HTTP schema, parameters, and responses. +* [Python SDK](https://pypi.org/project/warp-platform-sdk/) - Install `warp-platform-sdk` to make typed requests from Python. +* [TypeScript SDK](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) - Install `@warp-dot-dev/warp-platform-sdk` to make typed requests from TypeScript. +* [API errors](/factories/api-and-sdk/troubleshooting/errors/) - Resolve error responses by HTTP status and machine-readable code. +* [Factory MCP](/factories/factory-mcp/) - Exchange work between a factory and a connected coding agent or MCP client. +* [Custom webhooks](/factories/webhooks/) - Receive events from systems that can send JSON and route matching deliveries into factory automations. ## Get started diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 8e044192a..75459308a 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -12,25 +12,23 @@ The factory endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to find ## How it works -* `GET /factory` - list factories your account can access. Add `search` to filter by name or alias, case-insensitive. -* `GET /factory/{uid}` - get one factory by UID. -* `POST /factory/{uid}/runs` - dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. +* `GET /factory` - List the factories your account can access. Add `search` to filter by name or alias, case-insensitive. +* `GET /factory/{uid}` - Get one factory by UID. +* `POST /factory/{uid}/runs` - Dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [agent and run endpoints](/factories/api-and-sdk/) used for any run. ## Choosing an endpoint family -Use factory endpoints to find or start work on a factory. Use Agent & run endpoints for everything else: a standalone cloud agent, run management, or orchestration. +Use factory endpoints to find a factory or start work on it. Use the agent and run endpoints for everything else: a standalone cloud agent, run management, or orchestration. | Task | Recommended API | | --- | --- | -| Find a factory by name before dispatching to it | factory endpoints - `GET /factory?search=` | -| Start a new task on a factory | factory endpoints - `POST /factory/{uid}/runs` | -| Continue, monitor, or cancel a run (factory or standalone) | Agent & run endpoints - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | -| Run a standalone cloud agent with no factory involved | Agent & run endpoints - `POST /agent/runs` | -| Build a multi-agent orchestration | Agent & run endpoints - see [multi-agent orchestration](/platform/orchestration/) | - -Every factory run is still an ordinary run, so Agent & run endpoints handle status, follow-ups, and cancellation no matter which endpoint family started it. +| Find a factory by name before dispatching to it | `GET /factory?search=` (factory endpoints) | +| Start new work on a factory | `POST /factory/{uid}/runs` (factory endpoints) | +| Continue, monitor, or cancel a run (factory or standalone) | `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` (agent and run endpoints) | +| Run a standalone cloud agent with no factory involved | `POST /agent/runs` (agent and run endpoints) | +| Build a multi-agent orchestration | The agent and run endpoints; see [multi-agent orchestration](/platform/orchestration/) | ## Discover a factory @@ -42,11 +40,11 @@ from warp_platform_sdk import WarpClient client = WarpClient(api_key=os.environ.get("WARP_API_KEY")) -# Find a factory by name or alias — no UIDs needed up front +# Find a factory by name or alias, with no UID needed up front page = client.factories.list(search="payments") factory = page.factories[0] -# With the pagination scheme wired, iteration auto-pages +# Iterating over the result fetches every page of matches for f in client.factories.list(search="payments"): print(f.uid, f.name) ``` @@ -95,7 +93,7 @@ Content-Type: application/json } ``` -Every field except `prompt` is optional. Omit `title` and the server derives one from the prompt. `ticket_ref` identifies the originating ticket in `:` form (for example `linear:PAY-123` or `jira:PROJ-456`); pass `ticket_url` to link the factory's task record back to it, or omit both for an adhoc reference. +Every field except `prompt` is optional. Omit `title` and the server derives one from the prompt. `ticket_ref` identifies the originating ticket in `:` form (for example `linear:PAY-123` or `jira:PROJ-456`); pass `ticket_url` to link the factory's work item back to it, or omit both for an ad hoc reference. ## Continue and monitor the run @@ -120,7 +118,7 @@ See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of r ## Related pages * [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including factory endpoints alongside Slack, GitHub, and Factory MCP. -* [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. +* [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory, dispatches work, and continues it from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. -* [Agent & run endpoints](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying {VARS.WARP_PLATFORM_API}. -* [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched task moves through after the foreman picks it up. +* [Agent and run endpoints](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying {VARS.WARP_PLATFORM_API}. +* [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched work item moves through after the foreman picks it up. diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 9b4bfc330..2dcc0048a 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -9,14 +9,14 @@ sidebar: import AgentOnly from '@components/AgentOnly.astro'; import { VARS } from '@data/vars'; -Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories. An agent can send work to a factory, pull down a task to continue locally, and return the result. +Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories. An agent can send work to a factory, pull down a task to continue locally, and return the result. A task is what the MCP tools call a factory [work item](/factories/how-factories-work/). ## What you can use it for * **Send work in** - Turn anything from your local session into a factory task: a bug you found, review feedback, or a half-finished change. * **Continue a task locally** - Pull a task's context into your own checkout, work with your own tools, and return the result to the same task. -* **Stay in sync** - List and search tasks, read a task's conversation, and message its [foreman](/factories/factory-agents/), the agent that orchestrates each task inside the factory. -* **Create a factory** - Let your coding agent guide you through choosing a team, code host, repositories, factory agents, and integrations. +* **Stay in sync** - List and search tasks, read a task's conversation, message its [foreman](/factories/factory-agents/), and check what's waiting on you in your [inbox](/factories/factory-inbox/). +* **Create and connect a factory** - Let your coding agent guide you through choosing a team, code host, repositories, factory agents, and integrations, and attach Slack, Linear, or Jira to a factory later. * **Edit a factory's definition** - Read the definition schema and validate a factory's [definition files](/factories/factory-as-code/) before opening a pull request. ## Connect and authenticate @@ -121,23 +121,25 @@ Sending work to a factory means you're no longer watching it. To be notified whe ## Tool reference -Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [factory dashboard](/factories/factory-dashboard/). -The onboarding tools from `list_teams` through `create_factory` require browser sign-in. +Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the [factory dashboard](/factories/factory-dashboard/). The onboarding tools from `list_teams` through `create_factory` require browser sign-in. | Tool | What it does | | --- | --- | | `list_factories` | Lists the factories you can access. | +| `list_inbox` | Lists the unresolved [inbox](/factories/factory-inbox/) items waiting on you, or on your team. | | `get_factory_file_schema` | Returns the JSON Schema documents for factory definition files, as a catalog or one document at a time. | | `validate_factory_files` | Validates a complete factory definition tree without saving or applying it. | | `list_teams` | Lists current memberships and first-time joinable team choices. | | `create_team` | Creates the authenticated user's first team with a confirmed name. | | `join_team` | Joins a team selected from the first-time discovery choices. | -| `get_team_funding_status` | Checks first-team credit readiness and returns the browser checkout step when required. | +| `get_team_funding_status` | Checks whether a first team has credits and returns the browser checkout step when it doesn't. | | `list_forge_repositories` | Lists repositories available through a team's connected GitHub or GitLab account. | -| `list_tracker_scopes` | Lists the Linear teams or Jira projects that can be scoped to route issues to a new factory. | +| `list_tracker_scopes` | Lists the Linear teams or Jira projects that can route issues to a new factory. | | `start_connection` | Starts or checks setup for GitHub, GitLab, Slack, Linear, or Jira. | | `get_connection_status` | Checks whether a browser authorization flow completed. | | `create_factory` | Creates a factory with the selected repositories, integrations, and optional factory agents. | +| `start_factory_learning` | Starts a foreman run that customizes a new or existing factory from its definition, integrations, and repository conventions. It consumes credits, so the agent asks before starting it. | +| `attach_integration` | Adds Slack, Linear, or Jira to an existing factory. | | `list_tasks` | Lists the tasks in one factory, with filters such as creator, stage, and date. | | `search_task` | Searches task titles across all factories you can access. | | `get_task` | Reads a task's status, run history, and outputs. Accepts a task ID or a reference such as a URL, issue, pull request, or branch. With `start_working=true`, also returns local setup guidance. | @@ -149,7 +151,7 @@ The onboarding tools from `list_teams` through `create_factory` require browser ## Related pages -* [**Definitions as code**](/factories/factory-as-code/) - Every file and key in a factory definition, the JSON Schema behind them, and how to validate a change. -* [**Factory agents**](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's tasks. -* [**How Warp Factories work**](/factories/how-factories-work/) - The task lifecycle and the agents that move work through it. -* [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and send it its first work item. +* [Factory definition syntax](/factories/factory-as-code/) - Every file and key in a factory definition, the JSON Schema behind them, and how to validate a change. +* [Factory agents](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's work. +* [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle and the agents that move work through it. +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send it its first work item. diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index eb87c381c..372438085 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -7,24 +7,22 @@ sidebar: label: "How factories work" --- -A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. - -Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance. +A factory is a team of cloud agents attached to a set of repositories. You talk to one of them, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, each of which owns one part of the software development lifecycle, and people make the key decisions along the way. A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way. ![Warp Factories system diagram showing work sources, automations, the foreman and stage agents, human handoff, the factory definition, platform execution, the factory dashboard, and the measure-and-improve loop](../../../assets/agent-platform/factories-work-item-flow.png) -The diagram's components, from intake to improvement: +The diagram, from intake to improvement: -* **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from [custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. -* **Automations** - [Automations](/factories/automations/) filter provider events and decide which agent handles them. Schedules fire them on a timer; direct requests go straight to the foreman. -* **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the Triage, Spec, Implement, and Review agents as the work needs them. See [factory agents](/factories/factory-agents/) and the stages below. -* **Human handoff** - The factory opens a pull request with evidence, updates the original work item, and you review and merge. -* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks define the factory, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/). -* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/). -* **Factory dashboard** - Metrics, work items by stage, and runs and costs. See the [factory dashboard](/factories/factory-dashboard/). -* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and self-improvement turns repeat failures into follow-up pull requests for your review. +* **Work sources** - [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), [factory endpoints](/factories/factory-api/), the [Factory MCP](/factories/factory-mcp/), direct runs, and schedules. +* **Automations** - [Automations](/factories/automations/) filter provider events and schedules and decide which agent handles them. Direct requests go straight to the foreman. +* **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the triage, spec, implement, and review agents as the work needs them. See [factory agents](/factories/factory-agents/). +* **Human handoff** - The factory opens a pull request with evidence and updates the original work item. You review and merge. +* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/). +* **Execution** - Every stage is a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and each stage's configured model and [harness](/platform/harnesses/). +* **Factory dashboard** - Metrics, work items by stage, runs, and costs. See the [factory dashboard](/factories/factory-dashboard/). +* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and Self-improvement turns repeated failures into pull requests for your review. ## How a work item moves through the factory @@ -64,7 +62,7 @@ Stages and agents are named separately, so the spec agent works the Planning sta ## Where your team stays in charge -A factory is built to pause when there is a decision that needs to be made by a person. By default, that's three places: +A factory pauses when a person needs to decide. By default, that's three places: * **Approving the spec** - When work goes through the Planning stage, the Building stage waits until a person signs off on the plan. * **Answering questions** - When requirements are unclear or a review finding is ambiguous, the foreman asks instead of guessing. @@ -74,8 +72,14 @@ The first two are workflow policy, written into the foreman's instructions; edit ## How the factory improves itself -Your factory is self-improving, and you define what "better" means. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes — to the application code or to the factory's own definition. Every proposal arrives as a change for your review; nothing is adopted on its own. +[Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes to the application code or to the factory's own definition. Every proposal arrives as a pull request for your review; nothing is adopted on its own. The factory's definition is open to the same loop. Anyone on the team, or an agent, can propose changes to its instructions, skills, models, or other [definition files](/factories/factory-as-code/), and definitions stored in GitHub go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks) before a change reaches the production branch. -See [measure and improve](/factories/measure-and-improve/) for the evaluation workflow, or [build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) to apply the same pattern to a standalone agent. +## Related pages + +* [Sizing a factory](/factories/#sizing-a-factory) - Which repositories belong in one factory. +* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure it. +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory. +* [Measure and improve](/factories/measure-and-improve/) - Scorers, benchmarks, and Self-improvement. +* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) - Apply the same loop to a standalone agent. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index d0945518f..23b57f4ba 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -1,8 +1,8 @@ --- title: Warp Factories overview description: >- - Warp Factories is open infrastructure for building internal software - factories as code, from triage to implementation, review, and monitoring. + Warp Factories turns issues, tickets, and Slack requests into reviewed pull + requests with teams of cloud agents, while people approve specs and merges. sidebar: label: "Overview" --- @@ -10,7 +10,7 @@ import { VARS } from '@data/vars'; import { CardGrid, LinkCard } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; -A factory is a group of agents that shares repositories and delivery policy. Its foreman accepts work from connected tools, dispatches the right agents, and returns the result to the source. +A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns a pull request where the work started. +## What a factory does + +A coordinating agent called the foreman takes each request, decides which stages it needs, and dispatches the triage, spec, implement, and review agents in turn. The result comes back where the work started, usually as a pull request. For example, a factory can work through a backlog of issues, fix defects reported in a support channel, or review incoming pull requests across several repositories. + +People stay in the loop at the points that matter: approving a spec, answering the foreman's questions, and merging. + -## What is a software factory? +
+![A circular diagram of the software factory loop: triage, spec, implement, review, verify, ship, and monitor, with human review checkpoints for the spec, code, and product.](../../../assets/factories/factories-concept-loop.png) +
The software factory loop. The default agents cover triage through review.
+
-Each request becomes a work item, such as an issue, ticket, or triggered task. Specialized agents can triage it, write a specification, implement the change, and review the result. +## The parts of a factory -Each factory applies a single policy across its work sources, so deploy separate factories for repository groups that need different policies. +### Work items -### Sizing a factory +A work item is one request the factory acts on: an issue, a support thread, a pull request, or a scheduled job. It keeps its source context from intake to handoff, however many agents contribute along the way. -Size factories by product surface, not by workflow. Group the repositories that ship together into one factory. For example: +### Foreman and factory agents -* One factory for your main application -* One factory for your marketing site -* One factory for your data pipelines +Every factory has one foreman, the agent you talk to. It decides which agent a work item goes to next, asks you when it needs a decision, and hands back the finished pull request. Behind it are the default triage, spec, implement, and review agents; add custom agents for work they don't cover. Each agent can run on its own model and harness, including the Warp Agent, Claude Code, and Codex. See [factory agents](/factories/factory-agents/). -Don't split those same repositories across multiple factories by team or task (frontend vs. platform, for example). Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead. +Setup gives the foreman the same handle as the factory, so `payments` is the factory and `@payments` reaches its foreman from Slack or Linear. See [Foreman name](/factories/factory-agents/#foreman-name). -
-![A circular diagram of the software factory loop: triage, spec, implement, review, verify, ship, and monitor, with human review checkpoints for the spec, code, and product.](../../../assets/factories/factories-concept-loop.png) -
The general software factory loop. Warp Factories' default agents cover triage through review; add custom agents for the rest.
-
+### Stages and checkpoints -## Who benefits from Warp Factories +The foreman moves a work item through the Triage, Planning, Building, and Reviewing stages, skipping the ones a well-defined request doesn't need and sending work back when review finds problems. Spec approval and the foreman's questions are written into its instructions, which your team can edit. Merging is enforced by your repository's branch protection. See [how Warp Factories work](/factories/how-factories-work/). -Warp Factories is for engineering teams with repeatable work that extends beyond one coding session: +### Factory definition -* Process a backlog of issues with a consistent triage and delivery policy. -* Fix defects reported through support channels. -* Review incoming pull requests or maintain services across repositories. +A factory's repositories, agents, automations, runners, skills, and MCP servers are declared in definition files, either managed by Warp or stored in a GitHub repository your team owns. Changes to a GitHub-backed factory go through pull request review like any other code. See [definitions as code](/factories/factory-as-code/). -## What you get with Warp Factories +### Work sources -* **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover. -* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, [skills](/factories/factory-skills/), and MCP servers, so factory changes get the same review, history, and rollback as code changes. -* **Code forges and work sources** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), or [another code forge](/factories/code-forges/other-code-forges/) to the repository your factory works in. Route work from [Slack](/factories/integrations/slack/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), direct runs, or schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. -* **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. -* **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review. -* **Infrastructure control** - Choose Warp-hosted execution, or use managed self-hosted execution on an eligible Enterprise plan. The [infrastructure and security](/factories/infrastructure-and-security/) page compares execution models and links to the self-hosting setup path, as well as available inference and credential controls. +Connect [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), and the factory posts results back in the same thread, issue, or pull request. [Custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/) cover other systems, schedules start recurring work, and the [Factory MCP](/factories/factory-mcp/) lets a local coding agent hand work to a factory and take it back. See [connect your factory](/factories/connect-your-factory/). -## How Warp Factories fits into Warp +### Execution -Warp Factories builds on the same agent infrastructure used across Warp. Every factory agent produces a standard [cloud agent run](/platform/), so the same APIs, runners, models, security controls, and observability apply. +Every agent run in a factory is an ordinary [cloud agent run](/platform/) on the {VARS.WARP_AUTOMATION_PLATFORM}. Runs execute on Warp-hosted compute by default; Enterprise teams can keep checkout and execution on their own infrastructure with [managed self-hosting](/factories/self-hosting/). See [infrastructure and security](/factories/infrastructure-and-security/) for runners, inference, and credential boundaries. -| Product | Role | -| --- | --- | -| **Warp** | The interactive development experience for local work with agents and code review. | -| **Warp Agent** | The built-in agent harness that can power an individual factory agent. | -| **Warp Factories** | Multi-agent workflows for software development. | +### Measurement -## Key terms +The [factory dashboard](/factories/factory-dashboard/) shows work items by stage, runs, and cost per pull request. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, [benchmarks](/factories/benchmarks/) compare models, harnesses, and runners on the same tasks, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into pull requests for your review. See [measure and improve](/factories/measure-and-improve/). -Setup gives a factory and its foreman the same name by default, so it's easy to mistake one for the other. Here's how the terms differ: +## Sizing a factory -* **factory** - The repositories, delivery policy, agents, and connected tools that handle a related set of work. It is distinct from Warp Factories, the product, and from the foreman, its coordinating agent. -* **foreman** - The coordinating agent inside a factory, and the only one you talk to. It dispatches the other [factory agents](/factories/factory-agents/) and reports back. Every factory has exactly one. -* **Foreman name** - The handle your team @-mentions in Slack and Linear to reach the foreman. Setup copies it from the factory's name, so the two usually match even though they're different things. See [Foreman name](/factories/factory-agents/#foreman-name). +Group the repositories that ship together into one factory, and keep separate products in separate factories. For example: + +* One factory for your main application +* One factory for your marketing site +* One factory for your data pipelines -```mermaid -flowchart LR - subgraph Factory["One factory"] - Foreman["Foreman"] --> Agents["Triage, spec, implement,
and review agents"] - end - Slack["Slack or Linear"] -->|"@handle"| Foreman -``` +Don't split the same repositories across factories by team or task, such as frontend and platform. Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead. ## Related pages -* [**Set up a factory**](/factories/quickstart/) - Create a factory and send its first work item. -* [**Understand the execution model**](/factories/how-factories-work/) - See how the foreman coordinates stages, runs, and human decisions. -* [**Meet the factory agents**](/factories/factory-agents/) - See what each agent does and how to configure its model, harness, and instructions. -* **Adapt the system** - [Define the factory as code](/factories/factory-as-code/) and [connect its work sources](/factories/connect-your-factory/), or start from a working definition in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples). +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item. +* [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle, stage by stage. +* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure its model and harness. +* [Definitions as code](/factories/factory-as-code/) - The definition file format, with working examples in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples). diff --git a/src/content/docs/factories/webhooks.mdx b/src/content/docs/factories/webhooks.mdx index 151c5d31a..d0f18cfba 100644 --- a/src/content/docs/factories/webhooks.mdx +++ b/src/content/docs/factories/webhooks.mdx @@ -33,7 +33,7 @@ Choose the mode that fits what the sender can do: | **URL token** | `url_token` | Posts to a URL that embeds the secret as a path segment | Senders that only take a URL and can't set headers | | **Provider signature** | `signature` | Signs each request with its own scheme; Warp verifies the signature with the provider's signing secret | Vercel, Stripe, GitHub, Sentry, PagerDuty, and any sender that implements [Standard Webhooks](https://www.standardwebhooks.com/) (Svix-compatible headers are accepted) | -Warp generates the secret for bearer token and URL token webhooks and shows it once when you create the webhook. For a provider signature webhook, you supply the provider's own signing secret instead — or leave it blank for a Standard Webhooks-compatible sender, and Warp generates one for you to give the sender. Vercel, Stripe, and PagerDuty only issue their secret after you give them a URL; leave the secret blank for those too, and Warp takes it in a second step. See [Setting up a Vercel webhook](/factories/webhooks/vercel/), which covers all three. See [Manage webhooks](#manage-webhooks) to rotate a secret or roll a webhook over. +Warp generates the secret for bearer token and URL token webhooks and shows it once when you create the webhook. For a provider signature webhook, you supply the provider's own signing secret instead, or leave it blank for a Standard Webhooks-compatible sender and Warp generates one for you to give the sender. Vercel, Stripe, and PagerDuty only issue their secret after you give them a URL; leave the secret blank for those too, and Warp takes it in a second step, as described in [setting up a Vercel webhook](/factories/webhooks/vercel/). To rotate a secret or roll a webhook over, see [manage webhooks](#manage-webhooks). A URL token webhook's URL is itself the credential: treat it like a secret, and rotate it if it leaks. @@ -178,9 +178,9 @@ find the failing code path, and open a pull request with a fix and a test. ## Related pages -* [**Setting up a Vercel webhook**](/factories/webhooks/vercel/) - The two-step setup for providers that issue their signing secret only after they have a URL. -* [**Automations**](/factories/automations/) - How triggers and filters decide which events start work, including the payload filter grammar. -* [**Connect your factory**](/factories/connect-your-factory/) - Every way work reaches a factory, alongside custom webhooks. -* [**Definitions as code**](/factories/factory-as-code/) - The full schema for `webhooks/.yaml` and webhook triggers. -* [**Cloud agent secrets**](/platform/secrets/) - Create and rotate the managed secrets that file-defined webhooks reference. -* [**Factory dashboard**](/factories/factory-dashboard/) - Where the **Automations** page and its **Webhooks** tab live. +* [Setting up a Vercel webhook](/factories/webhooks/vercel/) - The two-step setup for providers that issue their signing secret only after they have a URL. +* [Factory automations](/factories/automations/) - How triggers and filters decide which events start work, including the payload filter grammar. +* [Connect your factory](/factories/connect-your-factory/) - Every way work reaches a factory, alongside custom webhooks. +* [Factory definition syntax](/factories/factory-as-code/#webhooksnameyaml) - The full schema for `webhooks/.yaml` and webhook triggers. +* [Cloud agent secrets](/platform/secrets/) - Create and rotate the managed secrets that file-defined webhooks reference. +* [Factory dashboard](/factories/factory-dashboard/) - Where the **Automations** page and its **Webhooks** tab live. diff --git a/src/content/docs/factories/webhooks/vercel.mdx b/src/content/docs/factories/webhooks/vercel.mdx index 752dd447c..4eb0ea00a 100644 --- a/src/content/docs/factories/webhooks/vercel.mdx +++ b/src/content/docs/factories/webhooks/vercel.mdx @@ -72,7 +72,7 @@ The secret Warp verifies with doesn't match the one Vercel signs with: the place ## Related pages -* [**Triggering automations with custom webhooks**](/factories/webhooks/) - Authentication modes, delivery rules, payload filters, and managing webhooks. -* [**Definitions as code**](/factories/factory-as-code/#webhooksnameyaml) - Every key in `webhooks/.yaml`. -* [**Cloud agent secrets**](/platform/secrets/) - The managed secrets that webhooks reference, and the `oz secret` commands. -* [**Vercel webhooks**](https://vercel.com/docs/webhooks) - Vercel's reference for webhook events and payloads. +* [Triggering automations with custom webhooks](/factories/webhooks/) - Authentication modes, delivery rules, payload filters, and managing webhooks. +* [Factory definition syntax](/factories/factory-as-code/#webhooksnameyaml) - Every key in `webhooks/.yaml`. +* [Cloud agent secrets](/platform/secrets/) - The managed secrets that webhooks reference, and the `oz secret` commands. +* [Vercel webhooks](https://vercel.com/docs/webhooks) - Vercel's reference for webhook events and payloads. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index e3695b83f..4f6eed92c 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -31,7 +31,7 @@ The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules, ## Warp Factories -A factory turns incoming engineering work into a repeatable, multi-stage workflow with specialized agents, review points, and measurable outcomes. +A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns a pull request where the work started. * [Warp Factories overview](/factories/) - Learn how a factory receives, routes, and tracks work. * [Factory quickstart](/factories/quickstart/) - Create a factory and send it its first work item.