Hosting the Agent SDK

Hosting Requirements

Container-Based Sandboxing

The Agent SDK requires a container-based sandbox environment for secure execution. See the TypeScript API documentation for programmatic sandbox configuration.

System Requirements

Understanding the SDK Architecture

The Agent SDK architecture:

• Executes commands in a persistent shell environment
• Manages file operations within a working directory
• Handles tool execution with context from previous interactions

Sandbox Provider Options

Choose a sandbox provider that fits your needs:

For more information on isolation technologies, see Secure Deployment.

Production Deployment Patterns

Pattern 1: Ephemeral Sessions

Create a new sandbox for each request, then shut it down when complete. Best for:

• Bug Investigation & Fix: Debug and resolve a specific issue with relevant context
• Invoice Processing: Extract and structure data from receipts/invoices for accounting systems
• Translation Tasks: Translate documents or content batches between languages
• Image/Video Processing: Apply transformations, optimizations, or extract metadata from media files

Pattern 2: Long-Running Sessions

Keep sandboxes running for extended periods. Best for:

• Email Agent: Monitors incoming emails and autonomously triages, responds, or takes actions based on content
• Site Builder: Hosts custom websites per user with live editing capabilities served through container ports
• High-Frequency Chat Bots: Handles continuous message streams from platforms like Slack where rapid response times are critical

Pattern 3: Hybrid Sessions

Balance between ephemeral and long-running. Best for:

• Personal Project Manager: Helps manage ongoing projects with intermittent check-ins, maintains context of tasks, decisions, and progress
• Deep Research: Conducts multi-hour research tasks, saves findings and resumes investigation when user returns
• Customer Support Agent: Handles support tickets that span multiple interactions, loads ticket history and customer context

Pattern 4: Single Containers

Run agents in a single container without sandboxing. Best for:

• Simulations: Agents that interact with each other in simulations such as video games

FAQ

How do I communicate with my sandboxes?

Communication methods vary by sandbox provider. Most providers offer APIs or CLI tools for managing sandbox lifecycle, file transfer, and process monitoring. Refer to your chosen provider's documentation for specific implementation details.

What is the cost of hosting a container?

Costs vary significantly by provider and deployment pattern:

• Ephemeral sessions: Pay per execution time (typically $0.001-$0.01 per second)
• Long-running sessions: Hourly or monthly rates (typically $0.05-$0.50 per hour)
• Resource-intensive tasks: Higher rates for CPU/memory-intensive operations

Check with your chosen provider for detailed pricing.

When should I shut down idle containers vs. keeping them warm?

Consider these factors:

• Shut down when: Usage is sporadic, cold start time is acceptable, cost optimization is priority
• Keep warm when: Response time is critical, frequent requests expected, user experience prioritized over cost
• Hybrid approach: Keep a pool of warm containers for peak times, scale down during low usage

How often should I update the CLI?

Update the bundled CLI regularly to:

• Get the latest bug fixes and performance improvements
• Access new features and tool capabilities
• Ensure compatibility with the latest API changes

Recommend updating monthly or when new features are announced.

How do I monitor container health and agent performance?

Implement monitoring for:

• Container metrics: CPU, memory, disk usage, network I/O
• Agent metrics: Turn count, tool execution time, error rates
• Application metrics: Request latency, throughput, success rates

Use tools like Prometheus, Grafana, Datadog, or your cloud provider's monitoring services.

How long can an agent session run before timing out?

Session limits vary by provider:

• Default timeout: Typically 30-60 minutes for most providers
• Extended sessions: Some providers offer longer sessions (up to several hours) for additional cost
• Custom limits: Contact your provider for custom timeout configurations

For very long-running tasks, consider implementing checkpoint/resume functionality.

Next Steps