Stacksona Integration Docs
Approval, policy, and audit controls for agent workflows across the tools teams already use.
Start with the integration path your workflow already uses.
Stacksona adds one decision point before an agent takes a sensitive action. Keep the workflow in n8n, Node, MCP, REST, or a platform recipe. Stacksona handles approval, signed decisions, and audit context.
The core integration is small: send the proposed action, wait for allow or approved, then execute only when the decision permits it.
Start here
Most teams should choose one of these four paths first. Platform recipes sit below for teams using agent builders without a native Stacksona package.
Install n8n-nodes-stacksona, add credentials, place Stacksona before the risky node, then branch on the decision.
Use @stacksona/sdk inside custom agents, workers, API routes, and backend services.
Expose Stacksona approval tools to MCP-compatible clients through @stacksona/mcp-server.
Call Stacksona directly from any platform that can make HTTP requests.
Replace STACKSONA_GATE_URL with your own Gate URL, usually shaped like https://{gate-id}.stacksona.cloud, and STACKSONA_API_KEY with your own sg_ agent key. Do not copy a sample hostname into production.
Plain Markdown for agents
Every public docs page has a plain Markdown version for agents, coding assistants, and internal search tools. Use the normal page URL for humans, or append .md to the clean public route to fetch Markdown only.
| Human page | Markdown page | Use |
|---|---|---|
https://docs.stacksona.com/integrations/n8n | https://docs.stacksona.com/integrations/n8n.md | Give an agent the n8n integration guide. |
https://docs.stacksona.com/reference/api-contract | https://docs.stacksona.com/reference/api-contract.md | Give an agent the full Gate API schemas. |
https://docs.stacksona.com/packages/sdk | https://docs.stacksona.com/packages/sdk.md | Give an agent the SDK usage guide. |
First successful call
Use this same request from REST, HTTP nodes, sidecars, and platform recipes. The workflow should execute the risky action only when Stacksona returns allow immediately or later returns approved.
curl -X POST "$STACKSONA_GATE_URL/api/agent/tasks/task_123/requests" \
-H "Authorization: Bearer $STACKSONA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_name": "Customer Support",
"task_label": "Approve customer email",
"tool_name": "send_email",
"subject": "Send reply to customer@example.com",
"preview": "Agent drafted a customer-facing reply.",
"risk_level": "medium"
}'Standard docs
Use these references from any platform. They explain the shared Gate API, schemas, statuses, security expectations, and reusable workflow templates.
Gate API Reference
ReferenceAll available agent endpoints, request schemas, response fields, webhooks, signed approval tokens, tool rules, and errors.
Decision Statuses
ReferenceHow to branch on allow, reject, pending_review, approved, and rejected.
Security
ReferenceAPI key handling, signed-token validation, fail-closed behavior, payload minimization, and environment separation.
Templates
ReferenceReusable approval patterns for email, CRM updates, refunds, production APIs, support replies, and deployments.
Platform recipes
These are documented as recipes, not native packages. Use them when the platform can call HTTP, run a sidecar, or invoke the Node SDK from a bridge service.
OpenAI Agents SDK
RecipeWrap risky function tools so approval happens before the tool executes.
LangGraph
RecipeUse Stacksona around graph interrupt, review, and resume points.
CrewAI
RecipeGate CrewAI tool execution before external, financial, customer-facing, or destructive actions.
Dify
RecipeUse HTTP request and human-input style workflow nodes to route decisions through Stacksona.
Make
RecipeCall Stacksona before Make scenarios mutate data, send messages, or call production APIs.
Zapier Agents
RecipeInsert Stacksona as a pre-action webhook before app actions.
Live packages
These are the Stacksona packages documented in this repo.
| Package | Current documented version | Use it for |
|---|---|---|
@stacksona/sdk | 0.2.0 | Node and TypeScript agents, services, and sidecars |
@stacksona/mcp-server | 0.2.3 | MCP-compatible approval and audit tools |
n8n-nodes-stacksona | 0.1.1 | n8n community node workflows |
@stacksona/agent-tools | 1.0.3 | Deterministic utility tools for agent workflows |
Popular integration searches
Find the exact Stacksona guide for common agent approval, human-in-the-loop, policy, audit, and tool-call governance searches.