Banata

Platform

Integration Patterns

Learn the main application patterns for Banata, from direct command flows to long-running agent jobs, human handoff, durable outputs, and webhook-driven systems.

This page is about using Banata well, not just calling methods.

The goal is to help you choose an architecture that matches the kind of product you are building.

Pattern 1: direct command flow

Use this when your app already knows exactly what should happen.

ts
const sandbox = await client.launch();
await sandbox.exec("sh", ["-lc", "python script.py"]);
const result = await sandbox.fs.read("/workspace/output.json");
await sandbox.kill();

Best for:

  • deterministic jobs
  • internal tools
  • known scripts and transformations

Pattern 2: long-running agent job

Use this when the job may take time or involves judgment.

ts
const sandbox = await client.launch({
  capabilities: {
    agent: { enabled: true, defaultAgent: "build" },
    browser: { viewport: { width: 1440, height: 900 } },
  },
});
 
const queued = await sandbox.promptAsync("Do the work", {
  metadata: {
    userId: "user_123",
    jobId: "job_456",
  },
});

Then:

  • store taskId
  • wait for a webhook
  • download outputs when finished

This is the best default pattern for production apps.

Pattern 3: human-in-the-loop flow

Use this when a person must step in.

Example:

  1. the agent opens a page and prepares context
  2. the app requests human handoff
  3. the person completes the manual step
  4. the agent resumes

This is ideal for:

  • approvals
  • verification challenges
  • account-specific manual steps

Pattern 4: document workflow

Use this when your app needs generated or transformed files.

Example:

  1. the agent gathers information
  2. it writes a report to /workspace
  3. the sandbox converts that report to PDF
  4. your app downloads the artifact

Pattern 5: pause and resume

Use this when a job should keep its workspace but does not need to stay active all the time.

Good for:

  • queued review work
  • internal operations
  • long-running customer jobs with manual checkpoints

Pattern 6: checkpoint before risk

Use a checkpoint before a step that may need rollback.

Good examples:

  • before a risky browser action
  • before handing over to a person
  • before a major document transformation

Recommended default architecture

For most apps:

  1. create or launch a sandbox
  2. call promptAsync() with metadata
  3. receive completion through a webhook
  4. inspect or download outputs
  5. kill the sandbox when done

That gives you:

  • low client complexity
  • clear task tracking
  • a clean async model

Related pages