Source: https://fireflyframework.org/weave/ Language: en Firefly Weave, a Python workflow platform built on pyfly # Business processes that cross systems and people. Draw a workflow in Studio or write it in YAML, JSON, or Python. Its runs wait for people and events while Weave records their history step by step. [Read the documentation](https://fireflyframework.github.io/firefly-weave/) [View the source](https://github.com/fireflyframework/firefly-weave) Built on pyfly · Studio, HTTP API, CLI, Python SDK How it works ## How a workflow becomes a run you can follow. YAML, JSON, and Python versions of a workflow compile to the same artifact digest before anything runs. Editing a draft never changes a run in progress. 1. ### Author Write the input schema, the steps, and the output schema, in Studio or in a file. 2. ### Compile The compiler checks schemas, Actions, and values against a catalog, then produces an artifact with a digest. 3. ### Publish Publishing stores an immutable version in a project. A change means a new version. 4. ### Activate Activation pins a version to an environment with its connections, worker releases, and human-⁠task assignments. 5. ### Run An input sent to an activation starts a run with its own state and history. 6. ### Observe Read a run’s status, output, history, and incidents in Studio, from the CLI, or through the API. Building blocks ## The steps a workflow is built from. A workflow is a tree of steps: a Decision or a Parallel group always joins again before the next step. Values come from expressions, since Weave has no scripting language. ### Actions and REST calls Describe an HTTPS call without code and Weave turns it into a reviewable Action on its built-in HTTP connector. OpenAPI documents can supply the operations. [Read the guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/connectors/http-without-code.md) ### Workers Your integration code runs in workers, processes that claim a task, call your system, and report the result through the API, with no database access. [Read the guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/guides/workers.md) ### Human tasks A human task waits for one authenticated person to choose an allowed decision on a form. Each environment binds the task to people or groups. [Read the guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/guides/human-tasks.md) ### Email conversations Weave sends mail through SMTP and reads a mailbox over IMAP without changing it. A reply carrying a valid routing token signals its run. [Read the guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/guides/email.md) ### Decision tables A decision table is a versioned policy with typed input and output that Weave evaluates inside the run, with no worker or provider call. [Read the reference](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/decision-tables.md) ### Events and schedules Schedules start runs on a UTC timetable. Signed webhooks, Kafka records, and email or messaging sources start a run or signal one. [Read about events](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/concepts.md#waiting-and-reacting-to-events) ### Files Steps pass verified file references. Weave stores the bytes apart from history, which stays readable. Replay never transfers a document again. [Read the guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/guides/files.md) ### AI tasks An AI task’s answer counts only when it matches its author’s contract. A Firefly Agentic worker makes the model call. [Read the guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/guides/ai-workers.md) ### Loops and sub-workflows A Loop over items step repeats its steps for each list item. A Call a workflow step runs a published version as a sub-workflow. [Read the step contracts](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/contracts.md#steps) Durability ## A run keeps its place through restarts and long waits. The Weave API stores workflow versions, run state, and tasks durably. Waits, signals, and human tasks are stored with the run and survive an API restart. History records what Weave accepted for a run, step by step. Recorded replay reads it offline without contacting anyone. Weave delivers external calls at least once, because a worker can crash after another system accepted its request. Steps that change another system must be idempotent. Weave retries an Action only when its declared side effect makes a repeat safe. Otherwise the run is suspended with an incident until an operator decides. [Read about tasks, leases, and retries](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/concepts.md#tasks-leases-and-retries) Code ## A customer check that waits for an approval signal. The repository’s customer-onboarding workflow asks another system about a customer, then waits up to a day for a manager’s decision. 1. ### Check the customer `check` calls a published Action that asks your system whether the customer is eligible. 2. ### Wait for approval `approval` waits for the `customer-approved` signal, whose payload must match its schema. 3. ### Decide `decision` is a Transform that accepts the customer only when both answers are true. In the Python SDK, `WorkflowBuilder` produces definitions like this one as data. `WeaveClient` publishes them and starts runs through the HTTP API. [Read the SDK reference](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/sdk.md) customer-onboarding.workflow.yaml ```yaml steps: - id: check kind: action uses: onboarding.check-customer@1.0.0 with: object: customerId: {ref: /input/customerId} - id: approval kind: signal name: customer-approved timeoutSeconds: 86400 payloadSchema: type: object additionalProperties: false required: [approved] properties: approved: {type: boolean} - id: decision kind: transform value: object: accepted: op: name: and args: - {ref: /steps/check/output/eligible} - {ref: /steps/approval/output/approved} output: {ref: /steps/decision/output} ``` [View the full file](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/examples/definitions/customer-onboarding.workflow.yaml#L36-L63) Deployment ## Run Weave as a service or inside your product. Your product calls Weave under its own identity and grants, and never needs the orchestration database. ### Standalone or embedded Run Weave as its own service, or embed its compiler and workflow builder, which need no server, database, or network. [Read the embedding guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/embedding.md) ### Python SDK and HTTP API The Python SDK describes workflows, controls a platform over its HTTP API, and runs your code in workers. Other languages call the HTTP API. [Read the SDK reference](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/sdk.md) ### Your identity provider Bring a compatible OIDC or CIAM provider. Weave verifies the provider’s tokens, then checks its own scoped grants for what a caller may do. [Read the identity guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/operations/identity-and-secrets.md) ### Container deployments Operations registers an existing Compose project, Kubernetes namespace, or Azure Container Apps environment. A runner beside it applies the plans people approve. [Read the deployment guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/operations/cluster-management.md) ### OpenTelemetry An API process can export metrics and traces to an OpenTelemetry collector over OTLP. Export stays off until you set `WEAVE_TELEMETRY`. [Read the observability guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/operations/observability.md) ### Studio’s Operate area Operators cancel a run, retry a finished one, or resolve an incident from Operate’s lists of runs and incidents. [Read the incident guide](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/incident-operations.md) Foundations ## Built on pyfly, with AI work on Firefly Agentic. Weave is a native pyfly application: dependency injection, controllers, and request filters come from the framework. You can embed the compiler on its own: importing it doesn’t start the application. An independent Firefly Agentic worker runs AI tasks. It calls the provider and model that the workflow’s AI profile specifies. The Firefly Software Foundation publishes Firefly Weave under the Apache License 2.0. [Explore pyfly](https://fireflyframework.org/frameworks/python/) [Explore Firefly Agentic](https://fireflyframework.org/agentic/) Sources and attribution Copyright 2026 Firefly Software Foundation. The workflow excerpt is shown unmodified. - [README](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/README.md) - [Concepts](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/concepts.md) - [Architecture](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/architecture.md) - [Compiler reference](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/compiler.md) - [History and replay](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/docs/reference/history-and-replay.md) - [Agentic worker package](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/workers/agentic/pyproject.toml) - [Apache License 2.0](https://github.com/fireflyframework/firefly-weave/blob/4c956beb999cb259c3e993b960871eed1a97b702/LICENSE) Next step ## Simulate a workflow on your computer. The Weave documentation covers installing the CLI and writing the workflow, and simulation needs no server. [Read the documentation](https://fireflyframework.github.io/firefly-weave/) [View the source](https://github.com/fireflyframework/firefly-weave)