> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buntime.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Integration

> Integrate buntime.sh with AI agents and assistants

## Overview

buntime.sh is designed for AI agents to write and execute code autonomously. This guide shows how to integrate buntime.sh with popular AI platforms including Claude, GPT, and custom agents via MCP (Model Context Protocol) or function calling.

## Why AI Agents Need buntime.sh

AI agents can write code, but they can't test it themselves. With buntime.sh, your AI can:

* ✅ Execute code and see real results
* ✅ Iterate on bugs with actual error messages
* ✅ Build multi-file projects that persist across messages
* ✅ Run web servers and preview them
* ✅ Work with databases without external setup

## Claude Integration

### Using MCP (Model Context Protocol)

Claude Desktop and other MCP-compatible clients can use buntime.sh as a tool:

```json mcp-config.json theme={null}
{
  "mcpServers": {
    "buntime": {
      "command": "npx",
      "args": ["-y", "@buntimesh/mcp-server"],
      "env": {
        "BUNTIME_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Install the MCP server:

```bash theme={null}
npm install -g @buntimesh/mcp-server
```

Now Claude can execute code directly:

```
User: "Can you calculate the fibonacci sequence up to n=10?"

Claude: "I'll write and execute code to calculate that."
[Uses buntime tool to execute code]

Claude: "Here are the results: [1, 1, 2, 3, 5, 8, 13, 21, 34, 55]"
```

### Using Function Calling

Provide buntime.sh as a function in your Claude API calls:

```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk';
import { Buntime } from 'buntime.sh';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });

// Create a session for this conversation
const session = await buntime.sessions.create();

const tools = [
  {
    name: "execute_code",
    description: "Execute JavaScript/TypeScript code in a persistent Bun runtime. Files and processes persist across calls. Use this to test code, process data, or run calculations.",
    input_schema: {
      type: "object",
      properties: {
        code: {
          type: "string",
          description: "The JavaScript/TypeScript code to execute"
        },
        files: {
          type: "array",
          description: "Optional files to write before execution",
          items: {
            type: "object",
            properties: {
              path: { type: "string" },
              content: { type: "string" }
            }
          }
        }
      },
      required: ["code"]
    }
  }
];

async function handleToolCall(toolName: string, toolInput: any) {
  if (toolName === "execute_code") {
    const result = await buntime.execute({
      sessionId: session.id,
      code: toolInput.code,
      files: toolInput.files
    });
    
    return {
      stdout: result.stdout,
      stderr: result.stderr,
      exitCode: result.exitCode
    };
  }
}

// Main conversation loop
const messages = [
  { role: "user", content: "Calculate the sum of numbers from 1 to 100" }
];

while (true) {
  const response = await anthropic.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    tools: tools,
    messages: messages
  });

  if (response.stop_reason === "tool_use") {
    for (const block of response.content) {
      if (block.type === "tool_use") {
        const result = await handleToolCall(block.name, block.input);
        
        messages.push({
          role: "assistant",
          content: response.content
        });
        
        messages.push({
          role: "user",
          content: [
            {
              type: "tool_result",
              tool_use_id: block.id,
              content: JSON.stringify(result)
            }
          ]
        });
      }
    }
  } else {
    console.log("Claude's response:", response.content);
    break;
  }
}
```

## OpenAI GPT Integration

### Using Function Calling

```typescript theme={null}
import OpenAI from 'openai';
import { Buntime } from 'buntime.sh';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });

const session = await buntime.sessions.create();

const tools = [
  {
    type: "function",
    function: {
      name: "execute_code",
      description: "Execute JavaScript/TypeScript code in a persistent runtime",
      parameters: {
        type: "object",
        properties: {
          code: {
            type: "string",
            description: "The code to execute"
          },
          files: {
            type: "array",
            description: "Optional files to create",
            items: {
              type: "object",
              properties: {
                path: { type: "string" },
                content: { type: "string" }
              }
            }
          }
        },
        required: ["code"]
      }
    }
  }
];

const messages = [
  { role: "user", content: "Create a function that reverses a string and test it" }
];

const response = await openai.chat.completions.create({
  model: "gpt-4-turbo-preview",
  messages: messages,
  tools: tools,
  tool_choice: "auto"
});

const toolCall = response.choices[0].message.tool_calls?.[0];

if (toolCall?.function.name === "execute_code") {
  const args = JSON.parse(toolCall.function.arguments);
  
  const result = await buntime.execute({
    sessionId: session.id,
    code: args.code,
    files: args.files
  });
  
  messages.push(response.choices[0].message);
  messages.push({
    role: "tool",
    tool_call_id: toolCall.id,
    content: JSON.stringify({
      stdout: result.stdout,
      stderr: result.stderr,
      exitCode: result.exitCode
    })
  });
  
  const finalResponse = await openai.chat.completions.create({
    model: "gpt-4-turbo-preview",
    messages: messages
  });
  
  console.log(finalResponse.choices[0].message.content);
}
```

## Custom Agent Integration

### LangChain

```typescript theme={null}
import { Tool } from "@langchain/core/tools";
import { Buntime } from 'buntime.sh';

class BuntimeTool extends Tool {
  name = "buntime_execute";
  description = "Execute JavaScript/TypeScript code in a sandboxed environment. Use this to test code, run calculations, or process data.";
  
  private client: Buntime;
  private sessionId: string;
  
  constructor(apiKey: string) {
    super();
    this.client = new Buntime({ apiKey });
  }
  
  async _call(input: string): Promise<string> {
    // Create session if not exists
    if (!this.sessionId) {
      const session = await this.client.sessions.create();
      this.sessionId = session.id;
    }
    
    try {
      const result = await this.client.execute({
        sessionId: this.sessionId,
        code: input
      });
      
      if (result.exitCode === 0) {
        return `Success!\nOutput: ${result.stdout}`;
      } else {
        return `Error (exit code ${result.exitCode}):\n${result.stderr}`;
      }
    } catch (error) {
      return `Execution failed: ${error.message}`;
    }
  }
}

// Use in LangChain agent
import { initializeAgentExecutorWithOptions } from "langchain/agents";
import { ChatOpenAI } from "@langchain/openai";

const tools = [new BuntimeTool(process.env.BUNTIME_API_KEY!)];
const model = new ChatOpenAI({ temperature: 0 });

const executor = await initializeAgentExecutorWithOptions(tools, model, {
  agentType: "openai-functions",
});

const result = await executor.invoke({
  input: "Calculate the factorial of 10"
});

console.log(result.output);
```

### Vercel AI SDK

```typescript theme={null}
import { streamText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { Buntime } from 'buntime.sh';
import { z } from 'zod';

const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });
const session = await buntime.sessions.create();

const result = await streamText({
  model: openai('gpt-4-turbo'),
  messages: [
    { role: 'user', content: 'Calculate fibonacci sequence up to n=10' }
  ],
  tools: {
    executeCode: tool({
      description: 'Execute JavaScript/TypeScript code',
      parameters: z.object({
        code: z.string().describe('The code to execute'),
      }),
      execute: async ({ code }) => {
        const result = await buntime.execute({
          sessionId: session.id,
          code: code
        });
        
        return {
          stdout: result.stdout,
          stderr: result.stderr,
          exitCode: result.exitCode
        };
      },
    }),
  },
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
```

## Session Management Strategies

### One Session Per Conversation

Best for AI assistants where context persists across messages:

```typescript theme={null}
class ConversationHandler {
  private buntime: Buntime;
  private sessions: Map<string, string> = new Map();
  
  constructor(apiKey: string) {
    this.buntime = new Buntime({ apiKey });
  }
  
  async getSession(conversationId: string): Promise<string> {
    if (!this.sessions.has(conversationId)) {
      const session = await this.buntime.sessions.create({
        ttl: 3600, // 1 hour
        metadata: { conversationId }
      });
      this.sessions.set(conversationId, session.id);
    }
    return this.sessions.get(conversationId)!;
  }
  
  async executeInConversation(conversationId: string, code: string) {
    const sessionId = await this.getSession(conversationId);
    return await this.buntime.execute({ sessionId, code });
  }
  
  async endConversation(conversationId: string) {
    const sessionId = this.sessions.get(conversationId);
    if (sessionId) {
      await this.buntime.sessions.delete({ sessionId });
      this.sessions.delete(conversationId);
    }
  }
}
```

### One Session Per Task

Best for independent tasks without shared context:

```typescript theme={null}
async function executeTask(task: string) {
  const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });
  
  // Create fresh session
  const session = await buntime.sessions.create({ ttl: 600 }); // 10 minutes
  
  try {
    // AI generates code based on task
    const code = await generateCodeWithAI(task);
    
    // Execute code
    const result = await buntime.execute({
      sessionId: session.id,
      code: code
    });
    
    return result;
  } finally {
    // Clean up
    await buntime.sessions.delete({ sessionId: session.id });
  }
}
```

## Error Handling for AI

Help your AI understand and fix errors:

```typescript theme={null}
async function executeWithRetry(
  buntime: Buntime,
  sessionId: string,
  code: string,
  maxRetries = 3
) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const result = await buntime.execute({ sessionId, code });
    
    if (result.exitCode === 0) {
      return {
        success: true,
        output: result.stdout,
        attempts: attempt
      };
    }
    
    if (attempt < maxRetries) {
      // Ask AI to fix the error
      const fixedCode = await askAIToFix(code, result.stderr);
      code = fixedCode;
    } else {
      return {
        success: false,
        error: result.stderr,
        attempts: attempt
      };
    }
  }
}
```

## Prompt Engineering Tips

### System Prompt Template

```typescript theme={null}
const SYSTEM_PROMPT = `
You are an AI assistant with the ability to execute code using buntime.sh.

When you need to test code, perform calculations, or verify logic:
1. Write clear, well-commented code
2. Use console.log() to output results
3. Handle errors gracefully
4. Test your code before declaring it works

Your code execution environment:
- Runtime: Bun 1.3 (Node.js compatible)
- Supports: TypeScript, JSX, npm packages (auto-installed)
- Persistent: Files and processes persist across executions in the same conversation
- Timeout: 30 seconds (default)

When sharing results:
- Always check the exit code (0 = success)
- Parse stdout for expected output
- Read stderr for error messages
- Iterate if tests fail

Example workflow:
User: "Sort this array: [3, 1, 4, 1, 5]"
You: Let me write and test the code.
[Execute: const arr = [3, 1, 4, 1, 5]; console.log(arr.sort((a,b) => a-b))]
[See output: [1, 1, 3, 4, 5]]
You: The sorted array is [1, 1, 3, 4, 5]
`;
```

### Encourage Good Practices

```typescript theme={null}
const CODE_EXECUTION_GUIDELINES = `
When using the code execution tool:

DO:
- Write self-contained, testable code
- Use descriptive variable names
- Add error handling for edge cases
- Log intermediate steps for debugging
- Verify output matches expectations

DON'T:
- Assume code works without testing
- Ignore stderr output
- Write code without console.log for verification
- Create infinite loops or long-running processes
- Hardcode sensitive data (use environment variables)

If code fails:
1. Read the error message carefully
2. Identify the root cause
3. Fix the specific issue
4. Test the fix
5. Only then confirm it works
`;
```

## Real-World Example: Data Analysis Agent

```typescript theme={null}
import { Buntime } from 'buntime.sh';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const buntime = new Buntime({ apiKey: process.env.BUNTIME_API_KEY });

async function analyzeData(csvData: string, question: string) {
  // Create session
  const session = await buntime.sessions.create();
  
  // Upload CSV data
  await buntime.files.write({
    sessionId: session.id,
    path: 'data.csv',
    content: csvData
  });
  
  // Ask Claude to analyze
  const response = await anthropic.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 2048,
    tools: [
      {
        name: "execute_analysis",
        description: "Execute data analysis code",
        input_schema: {
          type: "object",
          properties: {
            code: { type: "string" }
          },
          required: ["code"]
        }
      }
    ],
    messages: [
      {
        role: "user",
        content: `I have uploaded a CSV file at data.csv. ${question}\n\nWrite code to analyze it.`
      }
    ]
  });
  
  // Execute Claude's code
  for (const block of response.content) {
    if (block.type === "tool_use" && block.name === "execute_analysis") {
      const result = await buntime.execute({
        sessionId: session.id,
        code: block.input.code
      });
      
      console.log("Analysis results:", result.stdout);
      
      // Clean up
      await buntime.sessions.delete({ sessionId: session.id });
      
      return result.stdout;
    }
  }
}

// Usage
const csvData = `name,age,city
Alice,30,NYC
Bob,25,LA
Charlie,35,Chicago`;

await analyzeData(csvData, "What is the average age?");
```

## Security Considerations

<Warning>
  **Important security notes:**

  * Never pass untrusted user code directly to buntime.sh
  * Validate and sanitize AI-generated code
  * Set appropriate timeouts to prevent abuse
  * Monitor resource usage for anomalies
  * Use separate API keys for production and development
  * Review execution logs regularly
</Warning>

```typescript theme={null}
// Example: Sandboxing AI-generated code
function validateCode(code: string): boolean {
  // Check for dangerous patterns
  const dangerousPatterns = [
    /require\s*\(\s*['"]child_process['"]\s*\)/,
    /import.*from\s*['"]child_process['"]/,
    /process\.exit/,
    /while\s*\(\s*true\s*\)/,
  ];
  
  for (const pattern of dangerousPatterns) {
    if (pattern.test(code)) {
      console.warn('Potentially dangerous code detected');
      return false;
    }
  }
  
  return true;
}

async function safeExecute(sessionId: string, code: string) {
  if (!validateCode(code)) {
    throw new Error('Code validation failed');
  }
  
  return await buntime.execute({
    sessionId,
    code,
    timeout: 10 // Short timeout for safety
  });
}
```

## Best Practices

<AccordionGroup>
  <Accordion icon="recycle" title="Reuse sessions in conversations">
    Create one session per conversation to maintain context and file state across multiple code executions.
  </Accordion>

  <Accordion icon="clock" title="Set appropriate timeouts">
    Use shorter timeouts (10-30s) for quick tasks to prevent runaway code from consuming resources.
  </Accordion>

  <Accordion icon="message" title="Parse execution results">
    Check exitCode, stdout, and stderr to help the AI understand what happened and iterate if needed.
  </Accordion>

  <Accordion icon="shield" title="Validate AI-generated code">
    Review code for dangerous patterns before execution, especially in production environments.
  </Accordion>

  <Accordion icon="broom" title="Clean up sessions">
    Delete sessions when conversations end to free resources and minimize costs.
  </Accordion>
</AccordionGroup>

## Examples & Resources

<CardGroup cols={2}>
  <Card title="Claude MCP Server" icon="npm" href="https://github.com/buntimesh/mcp-server">
    Official MCP server for Claude integration
  </Card>

  <Card title="GPT Function Example" icon="openai" href="https://github.com/buntimesh/examples/tree/main/gpt-function">
    Complete GPT function calling example
  </Card>

  <Card title="LangChain Tool" icon="link" href="https://github.com/buntimesh/examples/tree/main/langchain">
    LangChain integration example
  </Card>

  <Card title="Agent Templates" icon="robot" href="https://github.com/buntimesh/agent-templates">
    Pre-built agent templates
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Multi-file Projects" icon="folder" href="/guides/multi-file-projects">
    Build complex applications with AI
  </Card>

  <Card title="Web Apps" icon="browser" href="/guides/web-apps">
    Create web servers with preview URLs
  </Card>

  <Card title="SDK Reference" icon="code" href="/sdk/introduction">
    Explore the TypeScript SDK
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    View complete API documentation
  </Card>
</CardGroup>