docs: add agentbay tools

docs/docs/integrations/tools/agentbay.ipynb

@@ -0,0 +1,351 @@
+{
+ "cells": [
+  {
+   "cell_type": "raw",
+   "id": "afaf8039",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "sidebar_label: AgentBay\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e49f1e0d",
+   "metadata": {},
+   "source": [
+    "# AgentbayIntegrationToolkit\n",
+    "\n",
+    "The AgentbayIntegrationToolkit provides a comprehensive set of tools for interacting with the AgentBay cloud computing platform. It includes tools for file operations, code execution, and command execution within a secure cloud environment.\n",
+    "\n",
+    "## Overview\n",
+    "\n",
+    "### Integration details\n",
+    "\n",
+    "| Class | Package | Serializable | JS support | Package latest |\n",
+    "| :--- | :--- | :---: | :---: | :---: |\n",
+    "| AgentbayIntegrationToolkit | langchain-agentbay-integration | ❌ | ❌ | 0.1.0 |\n",
+    "\n",
+    "### Tool features\n",
+    "\n",
+    "The AgentBay integration provides a secure cloud environment for executing code and commands with the following capabilities:\n",
+    "\n",
+    "1. **File Operations**: Write and read files with support for both overwrite and append modes.\n",
+    "2. **Code Execution**: Execute Python or JavaScript code in a secure environment.\n",
+    "3. **Command Execution**: Run shell commands with configurable timeout settings.\n",
+    "4. **Secure Sessions**: All operations occur within isolated AgentBay sessions."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "setup-section",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "To use the AgentBay integration, you need to get an API key from the [AgentBay Console](https://agentbay.console.aliyun.com/service-management) and configure it as an environment variable:\n",
+    "\n",
+    "```bash\n",
+    "export AGENTBAY_API_KEY=\"your-agentbay-api-key\"\n",
+    "export DASHSCOPE_API_KEY=\"your-dashscope-api-key\"\n",
+    "```\n",
+    "\n",
+    "### Prerequisites\n",
+    "\n",
+    "- **AgentBay account**: Register your AgentBay account.\n",
+    "- **AgentBay API key**: Get your API key from the AgentBay platform dashboard.\n",
+    "- **DashScope API key**: For using Qwen models with the agent. Visit [DashScope Platform](https://bailian.console.aliyun.com/#/home) to get your API key."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "652d6238-1f87-422a-b135-f5abbb8652fc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install -qU langchain-agentbay-integration wuying-agentbay-sdk"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "install-additional-deps",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%pip install -qU langchain-openai langgraph"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a38cde65-254d-4219-a441-068766c0d4b5",
+   "metadata": {},
+   "source": [
+    "## Instantiation\n",
+    "\n",
+    "Now we can instantiate our toolkit. First, we need to create an AgentBay session:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cb09c344-1836-4e0c-acf8-11d13ac1dbae",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import getpass\n",
+    "\n",
+    "if not os.environ.get(\"AGENTBAY_API_KEY\"):\n",
+    "    os.environ[\"AGENTBAY_API_KEY\"] = getpass.getpass(\"AgentBay API key:\\n\")\n",
+    "\n",
+    "from agentbay import AgentBay\n",
+    "from agentbay.session_params import CreateSessionParams\n",
+    "\n",
+    "# Create AgentBay session\n",
+    "agent_bay = AgentBay()\n",
+    "params = CreateSessionParams(image_id=\"code_latest\")\n",
+    "result = agent_bay.create(params)\n",
+    "session = result.session\n",
+    "\n",
+    "from langchain_agentbay_integration import AgentbayIntegrationToolkit\n",
+    "\n",
+    "toolkit = AgentbayIntegrationToolkit(session=session)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "invocation-section",
+   "metadata": {},
+   "source": [
+    "## Invocation\n",
+    "\n",
+    "### Invoke directly with args\n",
+    "\n",
+    "You can invoke individual tools from the toolkit directly using the direct instantiation approach:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "tools-list",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain_agentbay_integration.tools import (\n",
+    "    WriteFileTool,\n",
+    "    ReadFileTool,\n",
+    "    RunCodeTool,\n",
+    "    ExecuteCommandTool,\n",
+    ")\n",
+    "\n",
+    "# Create individual tools\n",
+    "write_tool = WriteFileTool(session=session)\n",
+    "read_tool = ReadFileTool(session=session)\n",
+    "code_tool = RunCodeTool(session=session)\n",
+    "command_tool = ExecuteCommandTool(session=session)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "invoke-write-file",
+   "metadata": {},
+   "source": [
+    "Let's invoke the WriteFileTool to create a file:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "invoke-write-file",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = write_tool.invoke(\n",
+    "    {\"path\": \"/tmp/hello.txt\", \"content\": \"Hello from AgentBay!\", \"mode\": \"overwrite\"}\n",
+    ")\n",
+    "print(result)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "invoke-read-file",
+   "metadata": {},
+   "source": [
+    "Now let's read the file back using the ReadFileTool:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "invoke-read-file",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "content = read_tool.invoke({\"path\": \"/tmp/hello.txt\"})\n",
+    "print(content)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "invoke-run-code",
+   "metadata": {},
+   "source": [
+    "Let's execute some Python code using the RunCodeTool:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "invoke-run-code",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = code_tool.invoke(\n",
+    "    {\"code\": \"print('Hello from Python in AgentBay!')\", \"language\": \"python\"}\n",
+    ")\n",
+    "print(result)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "invoke-execute-command",
+   "metadata": {},
+   "source": [
+    "Finally, let's execute a shell command using the ExecuteCommandTool:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "invoke-execute-command",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "result = command_tool.invoke(\n",
+    "    {\"command\": \"echo 'Hello from shell in AgentBay!'\", \"timeout_ms\": 5000}\n",
+    ")\n",
+    "print(result)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "use-within-agent",
+   "metadata": {},
+   "source": [
+    "## Use within an agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "310bf18e-6c9a-4072-b86e-47bc1fcca29d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.agents import AgentExecutor, create_tool_calling_agent\n",
+    "from langchain_core.prompts import ChatPromptTemplate\n",
+    "from langchain_openai import ChatOpenAI\n",
+    "\n",
+    "# Initialize LLM\n",
+    "llm = ChatOpenAI(\n",
+    "    api_key=os.getenv(\"DASHSCOPE_API_KEY\"),\n",
+    "    base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\",\n",
+    "    model=os.getenv(\"DASHSCOPE_MODEL\", \"qwen3-max\"),\n",
+    ")\n",
+    "\n",
+    "# Create prompt\n",
+    "prompt = ChatPromptTemplate.from_messages(\n",
+    "    [\n",
+    "        (\n",
+    "            \"system\",\n",
+    "            \"\"\"You are a helpful assistant with access to AgentBay tools that can write files, read files, execute code, and execute commands.\n",
+    "    \n",
+    "Available tools:\n",
+    "1. write_file - Write content to a file in the AgentBay session. Supports 'overwrite' and 'append' modes.\n",
+    "2. read_file - Read content from a file in the AgentBay session.\n",
+    "3. run_code - Execute code in the AgentBay session. Supported languages are: python, javascript.\n",
+    "4. execute_command - Execute a shell command in the AgentBay session\n",
+    "\n",
+    "Use these tools to help the user accomplish their tasks. When using write_file, you can specify the mode parameter to either overwrite (default) or append to a file. When appending content, make sure to include newline characters if needed to separate lines.\"\"\",\n",
+    "        ),\n",
+    "        (\"human\", \"{input}\"),\n",
+    "        (\"placeholder\", \"{agent_scratchpad}\"),\n",
+    "    ]\n",
+    ")\n",
+    "\n",
+    "# Create agent\n",
+    "agent = create_tool_calling_agent(llm, toolkit.get_tools(), prompt)\n",
+    "agent_executor = AgentExecutor(agent=agent, tools=toolkit.get_tools(), verbose=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "23e11cc9-abd6-4855-a7eb-799f45ca01ae",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "example_query = \"\"\"Write a Python file '/tmp/script.py' with content 'print(\"Hello from Python!\")\\nprint(\"AgentBay integration successful!\")\\n' using default mode.\n",
+    "Then run the Python code in that file using the run_code tool.\n",
+    "Next, write a file '/tmp/demo.txt' with content 'First line\\n' using default mode.\n",
+    "Then append a second line 'Second line\\n' to the same file using append mode.\n",
+    "After that, read the file '/tmp/demo.txt' to verify its content.\n",
+    "Finally, execute command 'cat /tmp/demo.txt' to show the file content.\"\"\"\n",
+    "\n",
+    "result = agent_executor.invoke({\"input\": example_query})\n",
+    "print(f\"Final result: {result['output']}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "toolkit-features",
+   "metadata": {},
+   "source": [
+    "## Toolkit Features\n",
+    "\n",
+    "The AgentbayIntegrationToolkit provides a comprehensive set of tools for working with the AgentBay platform:\n",
+    "\n",
+    "1. **WriteFileTool**: Write content to files in the AgentBay session with support for both overwrite and append modes.\n",
+    "2. **ReadFileTool**: Read content from files in the AgentBay session.\n",
+    "3. **RunCodeTool**: Execute Python or JavaScript code in a secure cloud environment.\n",
+    "4. **ExecuteCommandTool**: Run shell commands with configurable timeout settings.\n",
+    "\n",
+    "All tools work within the context of an AgentBay session, which provides a secure and isolated environment for code execution and file operations."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "api-reference",
+   "metadata": {},
+   "source": [
+    "## API reference\n",
+    "\n",
+    "API reference documentation will be available in the future."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}