diff --git a/docs/docs/integrations/tools/agentbay.ipynb b/docs/docs/integrations/tools/agentbay.ipynb new file mode 100644 index 0000000000000..c1eb54883afb5 --- /dev/null +++ b/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 +} \ No newline at end of file