# Elsai Prebuilt Tools — GitHub Copilot Instructions

This repository uses the **Elsai Prebuilt Tools** package (`elsai-agents-tools`) alongside the Elsai Agent SDK. Use these conventions when suggesting code that imports ready-made tools from `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"
```

Requires Python 3.10+ and `elsai-agents>=0.2.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

```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 here and read README.md")
print(result)
```

## Registering Tools

Import from `elsai_tools.<module>` and pass to `Agent(tools=[...])`. Do not redefine common tools with `@tool`.

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

result = agent.tool.shell(command="ls -la", work_dir="/app")  # direct call
result = agent("Summarise the project README")                 # natural language
```

## Class-Based 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

interpreter = AgentCoreCodeInterpreter(region="us-west-2")
browser = LocalChromiumBrowser()
memory = AgentCoreMemoryToolProvider(
    memory_id="memory-123",
    actor_id="user-456",
    session_id="session-789",
)

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

## Plugins + Prebuilt Tools

Plugins such as `AgentSkills` do not include file or shell tools — register both:

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

## 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 |

## Key Conventions

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