Platform guide

Stacksona for OpenAI Agents SDK

Q: What statuses should my workflow allow?

Execute the gated action only on allow or approved. Stop, retry, notify, or route to fallback for every other state.

Wrap function tools so the agent can propose an action, request Stacksona approval, and only execute the underlying function after approval.

RecipeNo native package yetSurface: Function tool wrapper or sidecar

Wrap risky function tools with a Stacksona check before the underlying function runs. This page shows the recommended integration pattern using HTTP, a wrapper, or a small bridge service.

Start with this decision step

Every recipe should create a Stacksona decision before the platform executes the risky action.

pseudo

1. Agent prepares a risky action.
2. Platform calls Stacksona with action details.
3. If decision is allow or approved, execute the action.
4. If decision is pending_review, wait, poll, or resume through callback.
5. If decision is reject or rejected, do not execute.

Recommended pattern

Step	Description
Tool wrapper	Wrap high-risk function tools. The wrapper requests a Stacksona decision before it invokes the original tool.
Human review	When Gate returns pending_review, return a pending state to the orchestration layer or wait in a controlled server-side path.
Signed token validation	Validate approval tokens before executing payments, deletes, or production changes.

Example

import { StacksonaGateClient } from '@stacksona/sdk';

const gate = new StacksonaGateClient({ baseUrl, apiKey });

export function withStacksonaApproval(toolName, action) {
  return async function approvedTool(args) {
    const { decision, executed, result } = await gate.runGatedAction(
      {
        taskId: args.taskId,
        workflowName: 'OpenAI Agent',
        taskLabel: `${toolName} request`,
        toolName,
        subject: `Agent wants to run ${toolName}`,
        riskLevel: args.riskLevel ?? 'medium',
        payload: args,
      },
      () => action(args),
      { validateSignedApprovalToken: true },
    );

    if (!executed) return { ok: false, status: decision.status };
    return { ok: true, result };
  };
}

Decision handling

Status	Workflow behavior
`allow`	Continue immediately.
`reject`	Stop the action before execution.
`pending_review`	Pause, poll, or wait for callback. Continue only after approved.
`approved`	Execute the action. Validate token first when signed approval is required.
`rejected`	Do not execute. Route to fallback, manual task, or safe response.

Integration FAQ

Can I use Stacksona with OpenAI Agents SDK today?

Yes. Use the documented native package when one exists. Otherwise, use the REST API, HTTP module, webhook action, or a small Node sidecar with @stacksona/sdk.

Where should Stacksona sit in a OpenAI Agents SDK workflow?

Place Stacksona immediately before the action that sends, updates, deletes, refunds, posts, deploys, or calls a production API.

What statuses should my workflow allow?

Execute the gated action only on allow or approved. Stop, retry, notify, or route to fallback for every other state.