Banata

Core Concepts

Agent Tasks

Learn when to use prompt versus promptAsync, how task tracking works, why metadata matters, and how to design webhook-driven agent workflows.

The AI agent is easiest to integrate when you treat its work as tasks.

That means:

  • you submit a prompt
  • Banata tracks the work as a task
  • you read status or receive a webhook later
  • the task produces outputs inside the sandbox

prompt() vs promptAsync()

prompt()

Use prompt() only for short, convenience-style tasks.

ts
const response = await sandbox.prompt("Reply with exactly OK");

promptAsync()

Use promptAsync() for real application work.

ts
const queued = await sandbox.promptAsync(
  "Research three pages, write the results to /workspace/report.md, and reply when done.",
  {
    metadata: {
      userId: "user_123",
      jobId: "job_456",
      source: "customer-portal",
    },
  },
);

This returns quickly with a taskId.

Task states

When you read a task later, you will typically see one of:

  • queued
  • running
  • completed
  • failed

Read a task:

ts
const task = await sandbox.getAgentTask(queued.taskId!);
console.log(task?.status);

Why metadata matters

Metadata lets you attach your own identifiers to the task so that when Banata later sends a webhook, your app can immediately know:

  • which user the task belonged to
  • which job record should be updated
  • which workflow triggered the work

Recommended production pattern

  1. create or launch a sandbox
  2. call promptAsync()
  3. store taskId
  4. attach meaningful metadata
  5. receive completion through a webhook
  6. read files or download artifacts

When to check task state directly

Direct reads like getAgentTask() are useful when:

  • you are debugging
  • you are building an admin console
  • you want a manual status page

Related pages