Skip to main content
A Procedure is a Python function that runs in an isolated Vercel Sandbox VM and communicates back to the platform through the gloo-procedure-sdk. It is the right tool for algorithmic work — pagination, data transformation, file generation, bulk API calls — where determinism, reproducibility, and sandboxed execution matter more than reasoning. This guide is for builders authoring new Procedures. For using an existing Procedure as a workflow node or agent tool, see the individual procedure reference pages (e.g. core-filter-by-date-range, linear-paginate-issues).

How Procedures connect to the platform

A Procedure runs in a Vercel Sandbox VM with no direct database access. It reads inputs and writes outputs exclusively through the gloo-procedure-sdk, which makes HTTP calls back to Convex via the /api/v1/proceduresApi/* routes. Those routes validate the wire shapes and dispatch to the same executors used by Convex-native agents. This architecture means a Procedure’s put_file call hits exactly the same execution path as a Convex-native agent’s putFile tool call. The wire shapes are defined once and shared across both callers — drift between the SDK and the platform is detected at CI time.

The forge.yaml manifest

Every Procedure lives in a directory containing a forge.yaml manifest and a Python entry point. The manifest is the single source of truth for the procedure’s identity, I/O contract, sandbox config, and capability requirements.

Key manifest fields

Versioned accounting operation contracts

Accounting procedures may declare an operationContract when they implement a portable business operation through a vendor-specific client. The shared operation id and version describe what the procedure does; the binding records how this implementation reaches the vendor:
The initial accounting vocabulary defines fetch-ar-aging, fetch-ap-aging, and fetch-gl-detail. All three return only rows: array<object>; the aging operations also require asOfDate in MM/DD/YYYY form. A string description may annotate rows, but a manifest cannot add another output, constrain the row objects, or change the shared shape. The binding’s vendorKey and connectionName must exactly match one entry of apiIntegrations. That entry is the procedure’s primary Connection; any other entries are auxiliary Connections the procedure also calls. Vendor-only inputs remain valid outside the portable contract—for example, an Intacct location identifier can accompany asOfDate without becoming part of every vendor implementation. Change the shared version when portable inputs or outputs change; do not silently redefine an existing version in a vendor manifest.

Several Connections

apiIntegrations is an ordered list: one entry per vendor Connection the procedure calls, including two Connections on one vendor. A target (vendorKey/connectionName) may appear only once. Each Connection resolves its own Credential, which is bound to that Connection’s host alone. The sandbox receives each Connection’s values under its own namespace: <VENDOR> and <CONNECTION> are the vendorKey and connectionName in upper case, with each run of other characters replaced by one _. For example, sage_intacct/xml becomes GLOO_CONN_SAGE_INTACCT__XML__API_BASE_URL. There is no flat GLOO_API_BASE_URL. The connection clients read their own names, so prefer them over reading the variables directly.

Prefer the connection client

Protocol behavior belongs to the engineered client for the Procedure’s exact (vendorKey, connectionName) target. The client owns credential consumption, base URL and wire construction, pagination or polling, bounded retry, vendor error mapping, and response normalization. The Procedure owns the business operation: it maps typed Procedure inputs into a client method and maps that result into the manifest’s output contract. Before writing a direct HTTP or XML request:
  1. Inspect the connection with the Builder’s read-only getConnectionClient tool. For a client with resource families, start with its compact core-family index and search it with the requested accounting or operational terminology.
  2. Follow family → exact operation → referenced type: inspect the most relevant family, choose a returned public operation, then read only the referenced types needed for its filters and result mapping. Use get/read_one for a known vendor key, page/read_page for one bounded batch or resumable checkpoint, and iter/read_stream for a bounded multi-page traversal.
  3. Search with includeExtended: true only when core lacks the required grain. Core and extended affect discovery order only; they do not authorize a call or prove that an operation satisfies the Procedure. Use path: [] only when explicit complete API browsing is necessary.
  4. Retrieve the current generated contracts rather than copying operation signatures, schemas, or inventories into Procedure guidance. Use the selected operation’s exact pythonUsage and requiredPackages; unlisted methods are private and must not be called.
  5. If no client contract exists, preserve the grounded raw vendor fallback. If a contract exists but lacks the operation, fall back only when its authoringFallbackPolicy is raw_allowed; a client_only gap is client backlog. Keep vendor documentation as the grounding source for any raw fallback.
The generated catalog joins an explicit public-operation allowlist to signatures and annotations extracted from bundled Python source. Generation rejects missing or malformed public operations and rejects a builtin operationContract whose client module or allowlisted operation is absent. In Forge Console, open a Vendor’s connection row and select Client to inspect the same contract. Operations leads with friendly supported business actions and copyable Python usage. Implementation shows the authorized technical metadata and owned runtime files/tests. This surface is read-only and never includes credentials, environment values, or authenticated request captures.

Sage Intacct REST read workflows

For sage_intacct/oauth2, start with core family discovery, inspect an exact selected family, then inspect a returned typeName only when you need its fields. Search extended families only when core lacks the required grain; use path: [] only for explicit complete API browsing. This catalog is client_only: use the public IntacctRestClient surface and put a missing primitive on the connection-client backlog. Do not author raw Common Resources Query calls, configuration/admin access, mutations, or direct REST report requests. The examples below are copy-ready operation bodies. They keep pagination bounded, follow only explicit related keys, and persist the records with the opaque checkpoint. The Procedure—not the client—owns selection and interpretation. The workflow graph should pass typed dates, checkpoints, and file IDs and route the resulting file; it should not embed Sage field knowledge or accounting decisions.

Journal → source and lines

Vendor bills → payments and applications

Customer invoices → receipts and applications

Unreconciled bank transactions

These are REST object reads. The standard REST GL Details report remains the dedicated iter_gl_detail_rows operation. AR/AP aging and Custom Report Writer workflows use the separate sage_intacct/xml connection; do not reconstruct them from REST objects.

SDK primitives

Install the SDK:
All SDK calls are async. The entry point receives a context object from the SDK runtime:

put_file — write a file to platform storage

Writes content to platform storage and returns a fileId. The bind parameter tells the executor what scope to attach the file to.
source variants: bind variants:

invoke_capability — call a platform capability

Calls a capability registered on the deployment and returns the result. The capability proxy routes the call to the active provider (e.g. Linear for project_management).
The procedure must declare the capability domain in its forge.yaml under capabilities:. Calls to undeclared capabilities are rejected at executor preflight.

get_file — read a file from platform storage

Reads a file that was passed as an input to the procedure.

emit_progress — stream progress to the operator UI

Sends a progress update visible in the Forge Console while the procedure runs.
fraction is a float between 0.0 and 1.0. The console renders it as a progress bar. Call it periodically during long-running loops.

run_procedure — chain into another Procedure

Invokes another procedure from within the current sandbox run. The child procedure runs synchronously and its outputs are available as the return value.

Wire shapes and generated TypedDicts

The SDK’s wire shapes are canonically defined once on the platform as Zod schemas. The SDK’s Python TypedDicts in gloo_procedure_sdk._generated.procedure_wire are generated from those schemas, and a freshness check fails any change that leaves them stale, so the SDK and the platform validator cannot drift. You can import the generated types for static analysis:
The canonical wire shapes (what the platform’s Convex executor actually validates):

File bindings in workflow graphs

When a procedure declares a file output in forge.yaml, the workflow graph editor exposes it as a typed file binding. Downstream nodes can reference the output by name:
The executor resolves paginate.pagesFile to a platform fileId before spawning the filter sandbox. The procedure receives it in ctx.inputs["inputFile"] as an opaque string.

Built-in Procedures

Twelve procedures ship with the platform. They are the reference implementations for the patterns described in this guide.

Test a procedure

gloo_procedure_sdk is preinstalled in the procedure sandbox. It is not published as a package for your own machine, and it has no mock context, so test a procedure in two places:
  1. Its logic, locally. Keep the work that turns inputs into outputs in plain Python functions that take and return ordinary values, and unit-test those with pytest. Leave the SDK calls (get_file, put_file, invoke_capability) in a thin run that calls them.
  2. The whole procedure, in Forge. Build or refine it with Procedure Builder (Platform → Procedures). A version publishes only after it finalizes, passes validation in the sandbox and passes the judge, so the SDK calls are exercised against the platform before anything can call the procedure. With procedures:write, GET /api/v3/procedures/{procedureId}/latest-validation-run?version={version} reads the latest validation run of that version.

What to double-check before shipping

  • capabilities: in forge.yaml matches every SDK call. If you call invoke_capability with capabilityDomain: "project_management", project_management must be in the manifest’s capabilities list. Missing entries are caught at executor preflight, not at author time.
  • egressAllowlist is tight. Add only the hostnames your procedure actually calls. Capability proxy calls (invoke_capability) do not leave the sandbox network — they route through Convex — and should not appear in the allowlist.
  • bind.kind matches the declared output. Files declared in outputs: must use bind: { kind: "workflow_output", outputName: "..." } where outputName exactly matches the key in outputs.properties. Mismatches produce silent output-binding failures.
  • idempotent: true is accurate. The executor may retry a procedure run on transient failures. If your procedure has side effects that should not repeat, set idempotent: false.

Do it over the API

Writing a Procedure is source work; there is no API call that authors one. Once its version is in the catalog, these reads confirm what the platform registered. They use the FORGE_BASE set up in the Raw HTTP tab of the quickstart. The quickstart’s ACCESS_TOKEN does not carry every scope they need, so mint it again with scope=procedures:read from an app whose roles hold them (see Requesting scopes at token mint), or send a Personal key whose scopes include them. Read the version’s catalog entry and check that its capabilities, idempotency and exposure match the manifest:
Add ?version=<semver> to read a version other than the default. To see every version of the family, newest first, with its status and dispatch count:
Both reads need procedures:read. Procedures are homed at the deployment root, so a credential whose grants cover only org units below the root sees none of them, and a missing Procedure and one you may not read both answer 404. Source code and bundled files are never returned. Over MCP, forge_call_read_operation reads the same entry. It is in the default start job:

See also