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 thegloo-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 anoperationContract 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:
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:
- Inspect the connection with the Builder’s read-only
getConnectionClienttool. For a client with resource families, start with its compact core-family index and search it with the requested accounting or operational terminology. - 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_onefor a known vendor key,page/read_pagefor one bounded batch or resumable checkpoint, anditer/read_streamfor a bounded multi-page traversal. - Search with
includeExtended: trueonly 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. Usepath: []only when explicit complete API browsing is necessary. - Retrieve the current generated contracts rather than copying operation signatures, schemas, or inventories into Procedure guidance. Use the selected operation’s exact
pythonUsageandrequiredPackages; unlisted methods are private and must not be called. - If no client contract exists, preserve the grounded raw vendor fallback. If a contract exists but lacks the operation, fall back only when its
authoringFallbackPolicyisraw_allowed; aclient_onlygap is client backlog. Keep vendor documentation as the grounding source for any raw fallback.
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
Forsage_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
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: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 ingloo_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:
File bindings in workflow graphs
When a procedure declares a file output inforge.yaml, the workflow graph editor exposes it as a typed file binding. Downstream nodes can reference the output by name:
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:
- 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 thinrunthat calls them. - 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:inforge.yamlmatches every SDK call. If you callinvoke_capabilitywithcapabilityDomain: "project_management",project_managementmust be in the manifest’scapabilitieslist. Missing entries are caught at executor preflight, not at author time.egressAllowlistis 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.kindmatches the declared output. Files declared inoutputs:must usebind: { kind: "workflow_output", outputName: "..." }whereoutputNameexactly matches the key inoutputs.properties. Mismatches produce silent output-binding failures.idempotent: trueis accurate. The executor may retry a procedure run on transient failures. If your procedure has side effects that should not repeat, setidempotent: 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 theFORGE_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:
?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:
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
- Configure Sandbox — sandbox resource limits, base images, and snapshot strategy
- Compose a workflow — wire procedure nodes into workflow graphs
- core-filter-by-date-range · linear-paginate-issues · core-build-xlsx-workbook — built-in procedure reference pages

