# Elsai Prebuilt Tools — Cursor Rules

You are an expert in the **Elsai Prebuilt Tools** package (`elsai-agents-tools`) for building agents with ready-made tools in Python.

Requires **`elsai-agents>=0.2.0`** installed separately. Import namespace: **`elsai_tools`**.

## Installation

```bash
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents-tools==0.1.0
# With optional extras:
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[mem0-memory]==0.1.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[local-chromium-browser]==0.1.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[agent-core-code-interpreter]==0.1.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[diagram]==0.1.0"
```

## Core Imports

```python
from elsai import Agent
from elsai_tools.shell import shell
from elsai_tools.file_read import file_read
from elsai_tools.file_write import file_write
from elsai_tools.http_request import http_request
from elsai_tools.python_repl import python_repl
from elsai_tools.tavily import tavily_search
from elsai_tools.retrieve import retrieve
from elsai_tools.memory import memory
from elsai_tools.swarm import swarm
from elsai_tools.graph import graph
from elsai_tools.code_interpreter import AgentCoreCodeInterpreter
from elsai_tools.browser import LocalChromiumBrowser
from elsai_tools.agent_core_memory import AgentCoreMemoryToolProvider
from elsai_tools.a2a_client import A2AClientToolProvider
```

## Minimal Agent with Prebuilt Tools

```python
from elsai import Agent
from elsai_tools.shell import shell
from elsai_tools.file_read import file_read

agent = Agent(tools=[shell, file_read])
result = agent("List files in this directory and read README.md")
print(result)
```

## Registration

Import each tool from its module and pass to `Agent(tools=[...])`:

```python
from elsai import Agent
from elsai_tools.shell import shell
from elsai_tools.file_read import file_read
from elsai_tools.file_write import file_write
from elsai_tools.http_request import http_request

agent = Agent(
    model="us.amazon.nova-pro-v1:0",
    system_prompt="You are a helpful assistant with file and shell access.",
    tools=[shell, file_read, file_write, http_request],
)

# Direct tool call (bypass LLM)
result = agent.tool.shell(command="ls -la", work_dir="/app")
result = agent.tool.file_read(path="./data/config.json")
```

## Class-Based Tool Providers

```python
from elsai import Agent
from elsai_tools.code_interpreter import AgentCoreCodeInterpreter
from elsai_tools.browser import LocalChromiumBrowser
from elsai_tools.agent_core_memory import AgentCoreMemoryToolProvider
from elsai_tools.a2a_client import A2AClientToolProvider

interpreter = AgentCoreCodeInterpreter(region="us-west-2")
browser = LocalChromiumBrowser()
memory = AgentCoreMemoryToolProvider(
    memory_id="memory-123",
    actor_id="user-456",
    session_id="session-789",
    namespace="default",
)
a2a = A2AClientToolProvider(known_agent_urls=["http://agent.example.com"])

agent = Agent(tools=[
    interpreter.code_interpreter,
    browser.browser,
    *memory.tools,
    *a2a.tools,
])
```

## Tool Categories (common imports)

| Category | Import |
|---|---|
| File I/O | `from elsai_tools.file_read import file_read` |
| Shell | `from elsai_tools.shell import shell` |
| Web / HTTP | `from elsai_tools.http_request import http_request` |
| Search | `from elsai_tools.tavily import tavily_search` |
| RAG | `from elsai_tools.retrieve import retrieve` |
| Memory | `from elsai_tools.memory import memory` |
| Multi-agent | `from elsai_tools.swarm import swarm` |
| AWS | `from elsai_tools.use_aws import use_aws` |

## Optional Extras

| Extra | Enables |
|---|---|
| `mem0-memory` | `mem0_memory` |
| `elasticsearch-memory` | `elasticsearch_memory` |
| `mongodb-memory` | `mongodb_memory` |
| `local-chromium-browser` | `LocalChromiumBrowser` |
| `agent-core-code-interpreter` | `AgentCoreCodeInterpreter` |
| `diagram` | `diagram` |
| `rss` | `rss` |
| `a2a-client` | A2A client tools |

## With Plugins

Plugins do not include execution tools — register prebuilt tools separately:

```python
from elsai import Agent
from elsai.agent import AgentConfig
from elsai.plugins.skills import AgentSkills
from elsai_tools.file_read import file_read
from elsai_tools.shell import shell

plugin = AgentSkills(skills="./skills/")
agent = Agent(tools=[file_read, shell], config=AgentConfig(plugins=[plugin]))
```

## Key Rules

1. **Never mock** `file_read`, `shell`, `http_request`, etc. — import from `elsai_tools` when this package is installed.
2. **One import per module** — `from elsai_tools.shell import shell`, not `from elsai_tools import shell`.
3. **Class-based tools** — instantiate the provider, then pass `.code_interpreter`, `.browser`, or `*provider.tools`.
4. **`elsai-agents-tools` is separate** from `elsai-agents` and from plugins like `AgentSkills`.
5. **Check pip extras** before using browser, Mem0, diagram, RSS, or AgentCore tools.
6. **Use `agent.tool.<name>`** for direct invocation when arguments are already known.
7. **Do not write `@tool` stubs** for tools that already exist in `elsai_tools`.