# 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.3.1`** installed separately (`elsai-agents[a2a]>=0.3.1` for A2A client tools). Import namespace: **`elsai_tools`**.

## Installation

```bash
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ elsai-agents-tools==0.3.0
# With optional extras:
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[mem0-memory]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[elasticsearch-memory]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[mongodb-memory]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[local-chromium-browser]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[agent-core-code-interpreter]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[sandbox-daytona]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[a2a-client]==0.3.0"
pip install --extra-index-url https://elsai-agents.elsai.ai/root/ "elsai-agents-tools[diagram]==0.3.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
from elsai_tools.sandbox import AgentCoreSandboxTemplate, DaytonaSandboxTemplate
```

## 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,
])
```

## Sandbox Backends

For isolated workspace execution, use `Sandbox` from `elsai.execution` with a backend template — not host `shell`/`file_read` in production sandbox mode.

```python
import asyncio
from pathlib import Path
from uuid import uuid4
from elsai import Agent
from elsai.agent import AgentConfig
from elsai.execution import LocalSandboxBackend, Sandbox, workspace_id_for_run
from elsai.plugins.sandbox import SandboxPlugin
from elsai_tools.sandbox import AgentCoreSandboxTemplate

async def main() -> None:
    async with Sandbox(
        workspace_id=workspace_id_for_run(str(uuid4())),
        backend=AgentCoreSandboxTemplate(region="us-west-2"),
        ttl_seconds=7200,
        seed_from=Path("./my-repo"),
    ) as sandbox:
        agent = Agent(config=AgentConfig(sandbox=sandbox, plugins=[SandboxPlugin()]))
        await agent.invoke_async("Run tests and summarize results")

asyncio.run(main())
```

| Backend | Package / extra |
|---|---|
| `LocalSandboxBackend` | `elsai-agents` (dev only) |
| `AgentCoreSandboxTemplate` | `elsai-agents-tools[agent-core-code-interpreter]` |
| `DaytonaSandboxTemplate` | `elsai-agents-tools[sandbox-daytona]` |

## 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` |
| Task tracking | `from elsai_tools.write_todos import write_todos` |
| 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`, `AgentCoreSandboxTemplate` |
| `sandbox-daytona` | `DaytonaSandboxTemplate` |
| `diagram` | `diagram` |
| `rss` | `rss` |
| `a2a-client` | A2A client tools (requires `elsai-agents[a2a]>=0.3.1`) |

## With Plugins

Plugins do not include execution tools — register prebuilt tools separately. **`SandboxPlugin`** is auto-added when `AgentConfig(sandbox=...)` is set:

```python
from elsai import Agent
from elsai.agent import AgentConfig
from elsai.execution import Sandbox
from elsai.plugins.sandbox import SandboxPlugin
from elsai.plugins.skills import AgentSkills
from elsai_tools.file_read import file_read

plugin = AgentSkills(skills="./skills/")
agent = Agent(
    config=AgentConfig(sandbox=sandbox, plugins=[plugin, SandboxPlugin()]),
)
```

For host-only dev (no shared `Sandbox`), register host tools explicitly:

```python
agent = Agent(tools=[file_read, shell], config=AgentConfig(plugins=[plugin]))
```

## Permissions

Gate host `file_read` / `file_write` / `editor` with `AgentConfig.filesystem_permissions` and `shell` / `python_repl` / sandbox `execute` with `execution_permissions`. See Agentkit SDK editor configs. Sandbox `read_file` / `write_file` / `list_dir` are not filesystem-permissioned.

```python
from elsai.permissions import deny_secrets, deny_destructive, preset, execution_preset

agent = Agent(
    tools=[file_read, file_write, editor, shell],
    config=AgentConfig(
        workspace_root="/home/user/project",
        filesystem_permissions=[*deny_secrets(), *preset("workspace_only")],
        execution_permissions=[*deny_destructive()],
    ),
)
```

## 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`.
8. **Sandbox mode** — prefer `Sandbox` + `SandboxPlugin`; host `shell`, `file_read`, `file_write`, `python_repl`, and `environment` are blocked in production.
9. **Permissions** — set `filesystem_permissions` / `execution_permissions` on `AgentConfig` for host file and command tools.