# Letta Agent Tools

This directory contains Python tools for the Letta agent to interact with Bluesky.

## Directory Structure

```
tools/
├── bluesky/           # Bluesky-specific tools
│   ├── *.py          # Your tool files go here
│   └── example_tool.py  # Sample showing expected format
└── README.md         # This file
```

## Adding Your Existing Tools

1. **Copy your Python tool files** into the `tools/bluesky/` directory
2. **Ensure each file contains ONE tool function** as the main export
3. **Tool naming convention**: The filename should match the function name
   - Example: `create_bluesky_post.py` contains `def create_bluesky_post(...)`

## Required Tools for Bluesky

Based on your operational guide, these tools are referenced:

- `create_bluesky_post` - Creates posts or replies on Bluesky
- `like_bluesky_post` - Likes a specific post
- `repost_bluesky_post` - Reposts content to followers
- `quote_bluesky_post` - Quotes a post with commentary
- `update_bluesky_connection` - Follow/unfollow/block/mute operations
- `fetch_bluesky_posts` - Retrieves posts from feeds
- `get_bluesky_user_info` - Gets user profile information
- `update_bluesky_profile` - Updates the agent's profile
- `ignore_notification` - (May be handled by Letta core, not custom)

## Tool Format Requirements

Each Python tool file must:

1. **Use Google-style docstrings** with:
   - Brief description
   - `Args:` section documenting all parameters
   - `Returns:` section describing the return value
   - Optional `Example:` section

2. **Include type annotations** for all parameters and return values

3. **Access environment variables** for credentials:
   ```python
   import os
   username = os.getenv("BSKY_USERNAME")
   password = os.getenv("BSKY_APP_PASSWORD")
   service_url = os.getenv("BSKY_SERVICE_URL")
   ```

4. **Return meaningful results** (strings, JSON, or structured data)

See `tools/bluesky/example_tool.py` for a complete example.

## How It Works

When you run `deno task prep-agent`, the script will:

1. Check which tools are already attached to your agent
2. Search for tools in Letta's global tool registry
3. For missing tools, read the `.py` file from `tools/bluesky/`
4. Create the tool in Letta
5. Attach the tool to your agent

## After Adding Tools

Once you've copied your tool files into `tools/bluesky/`:

```bash
deno task prep-agent
```

This will automatically create and attach all tools to your agent.

## Updating Tools

If you modify a tool:

1. Update the `.py` file in `tools/bluesky/`
2. Delete the old tool from Letta (via UI or API)
3. Run `deno task prep-agent` to recreate it

Alternatively, use Letta's `client.tools.modify()` API to update existing tools.