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

# Tools Integration

> Framework-agnostic file tools for any AI provider

# AI Framework Tools

Use OpenFiles with any AI provider that supports tool calling - OpenAI, Anthropic Claude, and more. Support for Google Gemini and Cohere coming soon.

## How It Works

1. **Import the tools** - Get OpenFiles tool definitions
2. **Add to your AI** - Include tools in your AI requests
3. **Process responses** - Handle file operations automatically
4. **Continue conversation** - AI gets results and responds naturally

## Features

* ✅ **Multi-Provider Support** - Works with OpenAI, Anthropic, and more
* ✅ **Provider-Specific APIs** - Optimized for each AI provider's format
* ✅ **Selective Processing** - Only handles OpenFiles tools
* ✅ **Automatic Execution** - File operations happen seamlessly
* ✅ **Rich Error Handling** - Comprehensive error management

## Installation

Refer to the [SDK Overview](/guides/overview#import-paths) for installation instructions and import paths.

## Framework Examples

### OpenAI

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { OpenFilesTools } from '@openfiles-ai/sdk/tools'
  import OpenAI from 'openai'

  const tools = new OpenFilesTools({ 
    apiKey: process.env.OPENFILES_API_KEY 
  })
  const openai = new OpenAI({ 
    apiKey: process.env.OPENAI_API_KEY 
  })

  // Add OpenFiles tools to OpenAI
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{
      role: 'user',
      content: 'Create a vacation itinerary for 5 days in Paris and save it as paris-trip.md'
    }],
    tools: tools.openai.definitions
  })

  // Process file operations
  const processed = await tools.openai.processToolCalls(response)
  if (processed.handled) {
    console.log(`✅ Handled ${processed.results.length} file operations`)
  }
  ```

  ```python Python theme={null}
  from openfiles_ai.tools import OpenFilesTools
  import openai

  tools = OpenFilesTools(api_key=os.getenv('OPENFILES_API_KEY'))
  client = openai.OpenAI(api_key=os.getenv('OPENAI_API_KEY'))

  # Add OpenFiles tools to OpenAI
  response = client.chat.completions.create(
      model='gpt-4',
      messages=[{
          'role': 'user',
          'content': 'Create a vacation itinerary for 5 days in Paris and save it as paris-trip.md'
      }],
      tools=tools.openai.definitions
  )

  # Process file operations
  processed = await tools.openai.process_tool_calls(response)
  if processed.handled:
      print(f'✅ Handled {len(processed.results)} file operations')
  ```
</CodeGroup>

### Anthropic Claude

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { OpenFilesTools } from '@openfiles-ai/sdk/tools'
  import Anthropic from '@anthropic-ai/sdk'

  const tools = new OpenFilesTools({ 
    apiKey: process.env.OPENFILES_API_KEY 
  })
  const anthropic = new Anthropic({ 
    apiKey: process.env.ANTHROPIC_API_KEY 
  })

  // Add OpenFiles tools to Claude
  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    messages: [{
      role: 'user',
      content: 'Create a vacation itinerary for 5 days in Paris and save it as paris-trip.md'
    }],
    tools: tools.anthropic.definitions
  })

  // Process file operations
  const processed = await tools.anthropic.processToolCalls(response)
  if (processed.handled) {
    console.log(`✅ Handled ${processed.results.length} file operations`)
  }
  ```

  ```python Python theme={null}
  from openfiles_ai.tools import OpenFilesTools
  import anthropic

  tools = OpenFilesTools(api_key=os.getenv('OPENFILES_API_KEY'))
  client = anthropic.Anthropic(api_key=os.getenv('ANTHROPIC_API_KEY'))

  # Add OpenFiles tools to Claude
  response = client.messages.create(
      model='claude-sonnet-4-20250514',
      max_tokens=1024,
      messages=[{
          'role': 'user',
          'content': 'Create a vacation itinerary for 5 days in Paris and save it as paris-trip.md'
      }],
      tools=tools.anthropic.definitions
  )

  # Process file operations
  processed = await tools.anthropic.process_tool_calls(response)
  if processed.handled:
      print(f'✅ Handled {len(processed.results)} file operations')
  ```
</CodeGroup>

### Coming Soon

#### Google Gemini

*Integration with Google Gemini coming soon - stay tuned for updates!*

#### Cohere

*Integration with Cohere coming soon - stay tuned for updates!*

## Available Tools

| Tool                | Description            | Use Case                                                     |
| ------------------- | ---------------------- | ------------------------------------------------------------ |
| `write_file`        | Create new file        | AI generates shopping lists, itineraries, recipes            |
| `read_file`         | Read and display file  | AI reviews existing content before making changes            |
| `edit_file`         | Modify specific text   | AI fixes typos, updates lists, adds items                    |
| `list_files`        | Browse directory       | AI explores saved files to find what you need                |
| `append_to_file`    | Add content to end     | AI adds new items to lists, notes to journals                |
| `overwrite_file`    | Replace entire content | AI completely rewrites outdated documents                    |
| `get_file_metadata` | Get file info only     | AI checks file size, version, dates                          |
| `get_file_versions` | Access file history    | AI reviews changes over time or reverts to previous versions |

## File Organization

Use `basePath` to organize files by project:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const personalTools = new OpenFilesTools({ 
    apiKey: 'oa-...',
    basePath: 'personal/recipes'
  })

  const travelTools = new OpenFilesTools({ 
    apiKey: 'oa-...',
    basePath: 'travel/itineraries'
  })

  // Each tool set operates in its own namespace
  ```

  ```python Python theme={null}
  personal_tools = OpenFilesTools(
      api_key='oa-...',
      base_path='personal/recipes'
  )

  travel_tools = OpenFilesTools(
      api_key='oa-...',
      base_path='travel/itineraries'
  )

  # Each tool set operates in its own namespace
  ```
</CodeGroup>

## Advanced Usage

### Custom Tool Processing

<CodeGroup>
  ```typescript TypeScript theme={null}
  const tools = new OpenFilesTools({ 
    apiKey: 'oa-...',
    onFileOperation: (op) => {
      console.log(`📁 ${op.action}: ${op.path}`)
      // Custom logging, metrics, webhooks
    },
    onError: (error) => {
      console.error(`❌ File operation failed: ${error.message}`)
      // Custom error handling, retries, notifications
    }
  })

  // Use provider-specific processing
  const processed = await tools.openai.processToolCalls(response)
  // OR
  const processed = await tools.anthropic.processToolCalls(response)
  ```

  ```python Python theme={null}
  def on_file_operation(op):
      print(f'📁 {op.action}: {op.path}')
      # Custom logging, metrics, webhooks

  def on_error(error):
      print(f'❌ File operation failed: {error.message}')
      # Custom error handling, retries, notifications

  tools = OpenFilesTools(
      api_key='oa-...',
      on_file_operation=on_file_operation,
      on_error=on_error
  )

  # Use provider-specific processing
  processed = await tools.openai.process_tool_calls(response)
  # OR
  processed = await tools.anthropic.process_tool_calls(response)
  ```
</CodeGroup>

### Multi-Agent Workflows

```typescript theme={null}
// Create specialized agents with different file scopes
const recipeAgent = new OpenFilesTools({ 
  apiKey: 'oa-...',
  basePath: 'recipes'
})

const travelAgent = new OpenFilesTools({ 
  apiKey: 'oa-...',
  basePath: 'travel-plans'
})

const shoppingAgent = new OpenFilesTools({ 
  apiKey: 'oa-...',
  basePath: 'shopping-lists'
})

// Each agent works in isolated file spaces
// but can collaborate on shared projects
```

## Error Handling

<CodeGroup>
  ```typescript TypeScript theme={null}
  try {
    // Use the appropriate provider method
    const processed = await tools.openai.processToolCalls(response)
    // OR for Anthropic: const processed = await tools.anthropic.processToolCalls(response)
    
    for (const result of processed.results) {
      if (result.status === 'success') {
        console.log(`✅ ${result.function}: ${result.data?.path}`)
      } else {
        console.error(`❌ ${result.function}: ${result.error}`)
      }
    }
  } catch (error) {
    console.error('Tool processing failed:', error.message)
  }
  ```

  ```python Python theme={null}
  try:
      # Use the appropriate provider method
      processed = await tools.openai.process_tool_calls(response)
      # OR for Anthropic: processed = await tools.anthropic.process_tool_calls(response)
      
      for result in processed.results:
          if result.status == 'success':
              print(f'✅ {result.function}: {result.data.path if result.data else "completed"}')
          else:
              print(f'❌ {result.function}: {result.error}')
              
  except Exception as error:
      print(f'Tool processing failed: {error}')
  ```
</CodeGroup>

## When to Use Tools Integration

**Choose Tools Integration when:**

* You're using multiple AI providers (OpenAI, Anthropic, etc.)
* You want framework-agnostic file operations
* You need fine-grained control over tool processing
* You're building custom AI workflows

**Consider alternatives:**

* **[OpenAI Integration](/guides/openai-integration)** - If you only use OpenAI and want automatic setup
* **[Core Client](/guides/core-client)** - If you need direct file operations without AI tools

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="github" href="/resources/examples">
    See real multi-framework implementations
  </Card>

  <Card title="Core Client" icon="code" href="/guides/core-client">
    Need direct file operations without AI?
  </Card>
</CardGroup>