Skip to content
Tapotik AI

Command Palette

Search for a command to run...

Agents

Agents plan and execute multi-step work across your tools — up to 25 chained tool calls per run, with human approval gates on sensitive actions and a complete audit trail.

How a run works

  1. 1

    Define an agent

    An agent is a reusable configuration: instructions, a model, and the tools it may call. Define agents once via the API or the dashboard's visual builder.

  2. 2

    Start a run with a goal

    A run gives the agent a concrete goal. The agent produces a plan, then executes it step by step — calling tools, checking results and revising the plan when reality disagrees with it.

  3. 3

    Approve gated actions

    Tools marked requires_approval pause the run and emit an agent.run.awaiting_approval webhook. A human (or your code) approves or rejects, and the run resumes.

  4. 4

    Collect the verified result

    Before finishing, the agent runs a verification pass against the original goal. The final state, every tool call and every token spent are recorded in the audit log.

Create an agent

POST/v1/agents
app/agent.tstypescript
const agent = await client.agents.create({
  name: "Refund triage",
  model: "tapotik-2-pro",
  instructions:
    "Investigate refund requests. Verify order state in Stripe, check our refund policy, then issue or escalate.",
  tools: [
    { type: "hosted", name: "web_search" },
    { type: "function", function: getOrderSchema },
    {
      type: "function",
      function: issueRefundSchema,
      requires_approval: true, // human gate on the sensitive action
    },
  ],
  max_steps: 25,
});

Start a run

POST/v1/agents/{agent_id}/runs
terminalbash
curl https://api.tapotik.ai/v1/agents/agt_4kd82/runs \
  -H "Authorization: Bearer $TAPOTIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Customer usr_8f2k requests a refund for order ord_1231. Handle it.",
    "metadata": { "ticket": "SUP-4821" }
  }'

Runs are asynchronous. Poll GET /v1/agents/{agent_id}/runs/{run_id} or subscribe to webhooks for transitions.

Run lifecycle

StatusMeaning
queuedAccepted and waiting for a worker.
planningThe agent is producing or revising its execution plan.
executingTool calls are in flight — watch the live execution graph in the dashboard.
awaiting_approvalPaused on a gated action until a human approves or rejects.
verifyingChecking the outcome against the goal before completion.
completedFinished successfully — result available on the run object.
failedUnrecoverable error or max_steps exhausted; partial trace preserved.

Approvals

POST/v1/agents/runs/{run_id}/approvals/{approval_id}
typescript
await client.agents.runs.approvals.resolve("run_9c1x", "apr_55e2", {
  decision: "approve", // or "reject" with a reason
  note: "Verified order state manually — refund is valid.",
});
Approvals can also be resolved from Slack or email with one click — connect the integrations in Dashboard → Integrations.

Limits and billing

Runs bill the underlying model tokens plus 2 credits per run for orchestration. A run may chain up to 25 tool calls (Enterprise: custom). Concurrent runs scale with your plan — see rate limits.