How Developers Integrate an Agent with Stacksona Gate

Who this article is for
Use this article if you are adding Stacksona Gate calls to an AI agent or workflow.
Integration overview
Your agent should call Stacksona Gate at decision points only. Your existing agent framework still runs the task.
Basic flow:

1. Add the agent API key to your agent configuration.
2. Log events as the task progresses.
3. Request a decision before a gated action.
4. If the response is allow, proceed.
5. If the response is reject, stop the action.
6. If the response is pending_review, wait for a human decision.
7. Poll for the decision or receive it by webhook.
8. Continue only if the final decision is approved.

Authentication
All agent API requests use a Bearer token.
Example header:

Authorization: Bearer sg_your_api_key
Content-Type: application/json
Log an event
Use this when you want reviewers to see what happened during the task.
Endpoint:

POST /api/agent/tasks/{taskID}/events
Example body:

{
"event_type": "task.started",
"event_summary": "Customer requested refund for order #8821",
"payload": {
"customer_id": "cus_99",
"order_id": "ord_8821"
}
}
Request a decision
Use this before a gated action.
Endpoint:

POST /api/agent/tasks/{taskID}/requests
Example body:

{
"workflow_name": "Customer Support",
"task_label": "Refund request — Order #8821",
"tool_name": "issue_refund",
"subject": "Issue refund of $500 to customer cus_99",
"preview": "Item never arrived per carrier.",
"risk_level": "high",
"summary": [
"Order placed 14 days ago via web",
"No tracking movement after day 2",
"1 prior refund in past 12 months"
],
"payload": {
"amount": 500,
"currency": "usd",
"order_id": "ord_8821",
"customer_id": "cus_99"
}
}
Possible decision request responses
The response status can be:

• allow: The agent may proceed immediately.
• reject: The agent must not proceed.
• pending_review: A human reviewer must decide.

Poll for a decision
Endpoint:

GET /api/agent/decisions?thread_id=THR-4F2A9C1B
You can also poll by task_id if needed.
Final decision statuses include:

• approved
• rejected

Developer best practices

• Use stable task IDs so logs and decisions stay connected.
• Include enough summary and payload context for a reviewer to decide.
• Never proceed on pending_review.
• Treat missing or invalid responses as a deny or retry condition.
• Log important steps before requesting review.
• Keep payloads structured and consistent so rules can match them.