langchain-agentcore-codeinterpreter 0.0.1__py3-none-any.whl

langchain_agentcore_codeinterpreter/__init__.py

@@ -0,0 +1,5 @@
+"""Amazon Bedrock AgentCore Code Interpreter sandbox integration for Deep Agents."""
+
+from langchain_agentcore_codeinterpreter.sandbox import AgentCoreSandbox
+
+__all__ = ["AgentCoreSandbox"]

langchain_agentcore_codeinterpreter/sandbox.py

@@ -0,0 +1,273 @@
+"""Amazon Bedrock AgentCore Code Interpreter sandbox backend implementation."""
+
+from __future__ import annotations
+
+import base64
+import logging
+from typing import TYPE_CHECKING, Any
+
+from deepagents.backends.protocol import (
+    ExecuteResponse,
+    FileDownloadResponse,
+    FileUploadResponse,
+)
+from deepagents.backends.sandbox import BaseSandbox
+
+if TYPE_CHECKING:
+    from bedrock_agentcore.tools.code_interpreter_client import CodeInterpreter
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_text_from_stream(response: dict[str, Any]) -> tuple[str, int | None]:
+    """Extract text output and exit code from a code interpreter response stream.
+
+    Iterates through the streamed response events and collects text content,
+    error messages, and the exit code.
+
+    Args:
+        response: Response dict from a code interpreter invocation.
+
+    Returns:
+        Tuple of (output_text, exit_code). The exit code is ``None`` when
+        the response stream does not include one.
+    """
+    output_parts: list[str] = []
+    exit_code: int | None = None
+
+    for event in response.get("stream", []):
+        if "result" not in event:
+            continue
+
+        result = event["result"]
+
+        if "exitCode" in result:
+            exit_code = result["exitCode"]
+
+        for content_item in result.get("content", []):
+            content_type = content_item.get("type")
+
+            if content_type == "text":
+                text = content_item.get("text", "")
+                output_parts.append(text)
+            elif content_type == "error":
+                error_msg = content_item.get("text", "Unknown error")
+                output_parts.append(f"Error: {error_msg}")
+                if exit_code is None:
+                    exit_code = 1
+
+    return "\n".join(output_parts), exit_code
+
+
+def _extract_files_from_stream(
+    response: dict[str, Any],
+    requested_paths: list[str],
+) -> dict[str, bytes]:
+    """Extract file contents from a code interpreter ``readFiles`` response.
+
+    Matches ``file://`` URIs in the response back to the original requested
+    paths by stripping leading slashes for comparison.
+
+    Args:
+        response: Response dict from a code interpreter ``readFiles``
+            invocation.
+        requested_paths: The original paths that were requested, used to
+            map URIs back to caller-provided names.
+
+    Returns:
+        Dict mapping original requested paths to their contents as bytes.
+    """
+    path_lookup: dict[str, str] = {}
+    for path in requested_paths:
+        stripped = path.lstrip("/")
+        path_lookup[stripped] = path
+
+    files: dict[str, bytes] = {}
+
+    for event in response.get("stream", []):
+        if "result" not in event:
+            continue
+        for item in event["result"].get("content", []):
+            if item.get("type") != "resource":
+                continue
+            resource = item.get("resource", {})
+            uri = resource.get("uri", "")
+            file_path = uri.replace("file://", "").lstrip("/")
+
+            content: bytes | None = None
+            if "text" in resource:
+                content = resource["text"].encode("utf-8")
+            elif "blob" in resource:
+                content = base64.b64decode(resource["blob"])
+
+            if content is not None:
+                original_path = path_lookup.get(file_path, file_path)
+                files[original_path] = content
+
+    return files
+
+
+class AgentCoreSandbox(BaseSandbox):
+    """AgentCore Code Interpreter sandbox conforming to SandboxBackendProtocol.
+
+    Wraps an active :class:`CodeInterpreter` session to execute shell commands
+    and manage files in a secure, isolated MicroVM environment.
+
+    This implementation inherits all file operation methods from
+    :class:`BaseSandbox` and implements the required ``execute()``,
+    ``download_files()``, and ``upload_files()`` methods using AgentCore's
+    streaming API.
+
+    The caller is responsible for managing the interpreter lifecycle
+    (``start()`` / ``stop()``).
+
+    Example:
+        .. code-block:: python
+
+            from bedrock_agentcore.tools.code_interpreter_client import (
+                CodeInterpreter,
+            )
+            from langchain_agentcore_codeinterpreter import AgentCoreSandbox
+
+            interpreter = CodeInterpreter(region="us-west-2")
+            interpreter.start()
+
+            backend = AgentCoreSandbox(interpreter=interpreter)
+            result = backend.execute("echo hello")
+            print(result.output)
+
+            interpreter.stop()
+    """
+
+    def __init__(self, *, interpreter: CodeInterpreter) -> None:
+        """Create a backend wrapping an active CodeInterpreter session.
+
+        Args:
+            interpreter: A started :class:`CodeInterpreter` instance.
+        """
+        self._interpreter = interpreter
+
+    @staticmethod
+    def _to_relative_path(path: str) -> str:
+        """Strip leading slashes so paths are relative for AgentCore APIs.
+
+        Args:
+            path: File path (absolute or relative).
+
+        Returns:
+            Relative path string.
+        """
+        return path.lstrip("/")
+
+    @property
+    def id(self) -> str:
+        """Return the AgentCore session ID."""
+        return self._interpreter.session_id or ""
+
+    def execute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,  # noqa: ARG002
+    ) -> ExecuteResponse:
+        """Execute a shell command inside the sandbox.
+
+        Args:
+            command: Shell command string to execute.
+            timeout: Unused. AgentCore does not support per-command timeouts.
+                Accepted for interface compatibility with
+                :class:`SandboxBackendProtocol`.
+
+        Returns:
+            Response containing the command output, exit code, and truncation
+            flag.
+        """
+        try:
+            response = self._interpreter.invoke(
+                method="executeCommand", params={"command": command}
+            )
+            output, exit_code = _extract_text_from_stream(response)
+            return ExecuteResponse(
+                output=output,
+                exit_code=exit_code if exit_code is not None else 0,
+                truncated=False,
+            )
+        except Exception as exc:
+            logger.exception("Error executing command: %s", command[:80])
+            msg = f"Error executing command: {exc}"
+            return ExecuteResponse(
+                output=msg,
+                exit_code=1,
+                truncated=False,
+            )
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download files from the AgentCore sandbox.
+
+        Uses AgentCore's ``readFiles`` API. Supports partial success —
+        individual file downloads may fail without affecting others.
+
+        Args:
+            paths: List of file paths to download.
+
+        Returns:
+            List of :class:`FileDownloadResponse` objects in the same order
+            as the input paths.
+        """
+        try:
+            relative_paths = [self._to_relative_path(p) for p in paths]
+            response = self._interpreter.invoke(
+                method="readFiles", params={"paths": relative_paths}
+            )
+            file_contents = _extract_files_from_stream(response, paths)
+
+            return [
+                FileDownloadResponse(
+                    path=path,
+                    content=file_contents.get(path),
+                    error=None if path in file_contents else "file_not_found",
+                )
+                for path in paths
+            ]
+        except Exception:
+            logger.exception("Error downloading files: %s", paths)
+            return [
+                FileDownloadResponse(path=path, content=None, error="file_not_found")
+                for path in paths
+            ]
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload files to the AgentCore sandbox.
+
+        Text files are sent directly; binary files are base64-encoded.
+
+        Args:
+            files: List of ``(path, content)`` tuples to upload.
+
+        Returns:
+            List of :class:`FileUploadResponse` objects in the same order
+            as the input files.
+        """
+        file_list: list[dict[str, str]] = []
+
+        for path, content in files:
+            rel_path = self._to_relative_path(path)
+            try:
+                text_content = content.decode("utf-8")
+                file_list.append({"path": rel_path, "text": text_content})
+            except UnicodeDecodeError:
+                encoded = base64.b64encode(content).decode("ascii")
+                file_list.append({"path": rel_path, "blob": encoded})
+
+        try:
+            if file_list:
+                self._interpreter.invoke(
+                    method="writeFiles", params={"content": file_list}
+                )
+            return [FileUploadResponse(path=path, error=None) for path, _ in files]
+        except Exception:
+            logger.exception("Error uploading files: %s", [p for p, _ in files])
+            return [
+                FileUploadResponse(path=path, error="permission_denied")
+                for path, _ in files
+            ]

langchain_agentcore_codeinterpreter-0.0.1.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: langchain-agentcore-codeinterpreter
+Version: 0.0.1
+Summary: Amazon Bedrock AgentCore Code Interpreter sandbox integration for Deep Agents
+Project-URL: Source Code, https://github.com/langchain-ai/langchain-aws/tree/main/libs/agentcore-codeinterpreter
+Project-URL: Repository, https://github.com/langchain-ai/langchain-aws
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentcore,aws,bedrock,code-interpreter,deepagents,langchain,sandbox
+Requires-Python: <4.0,>=3.11
+Requires-Dist: bedrock-agentcore>=1.1.4
+Requires-Dist: boto3>=1.42.42
+Requires-Dist: deepagents>=0.1.0
+Description-Content-Type: text/markdown
+
+# langchain-agentcore-codeinterpreter
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langchain-agentcore-codeinterpreter?label=%20)](https://pypi.org/project/langchain-agentcore-codeinterpreter/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langchain-agentcore-codeinterpreter)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langchain-agentcore-codeinterpreter)](https://pypistats.org/packages/langchain-agentcore-codeinterpreter)
+
+Amazon Bedrock AgentCore Code Interpreter sandbox integration for [Deep Agents](https://github.com/langchain-ai/deepagents).
+
+This package provides `AgentCoreSandbox` — a [`SandboxBackendProtocol`](https://docs.langchain.com/oss/deepagents/sandboxes) implementation that wraps AgentCore's [Code Interpreter](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore-code-interpreter.html), a secure, isolated MicroVM environment for executing code. The caller manages the interpreter lifecycle (`start()` / `stop()`); the sandbox backend handles command execution and file operations.
+
+> **Note:** For the LangChain `BaseTool` integration (used with `create_react_agent` and LangGraph agents), see [`langchain-aws[tools]`](https://github.com/langchain-ai/langchain-aws). This package is specifically for the Deep Agents `BaseSandbox` protocol.
+
+## Prerequisites
+
+**1. AWS credentials** configured via one of the following methods:
+
+```bash
+# Option 1: Long-lived IAM credentials
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export AWS_REGION="us-west-2"
+
+# Option 2: Temporary credentials (IAM roles, SSO, STS AssumeRole)
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export AWS_SESSION_TOKEN="your-session-token"
+export AWS_REGION="us-west-2"
+
+# Option 3: AWS CLI profile (picks up ~/.aws/credentials + ~/.aws/config)
+aws configure
+# or for SSO:
+aws configure sso
+aws sso login --profile your-profile
+```
+
+Any method supported by the [boto3 credential chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) works, including EC2 instance profiles, ECS task roles, and environment variables.
+
+**2. IAM permissions** — your credentials must allow `bedrock-agentcore:InvokeCodeInterpreter` (or the equivalent action for your region). See the [AgentCore Code Interpreter docs](https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore-code-interpreter.html) for the required IAM policy.
+
+**3. Region availability** — Code Interpreter is available in select AWS regions. `us-west-2` is a safe default. Pass the region to `CodeInterpreter(region=...)`.
+
+## Quick Install
+
+```bash
+pip install langchain-agentcore-codeinterpreter
+```
+
+## Usage
+
+### Standalone
+
+```python
+from bedrock_agentcore.tools.code_interpreter_client import CodeInterpreter
+
+from langchain_agentcore_codeinterpreter import AgentCoreSandbox
+
+interpreter = CodeInterpreter(region="us-west-2")
+interpreter.start()
+
+backend = AgentCoreSandbox(interpreter=interpreter)
+
+result = backend.execute("echo hello")
+print(result.output)  # "hello"
+
+interpreter.stop()
+```
+
+### With Deep Agents
+
+```python
+from bedrock_agentcore.tools.code_interpreter_client import CodeInterpreter
+from deepagents import create_deep_agent
+
+from langchain_agentcore_codeinterpreter import AgentCoreSandbox
+from langchain_aws import ChatBedrockConverse
+
+interpreter = CodeInterpreter(region="us-west-2")
+interpreter.start()
+
+model = ChatBedrockConverse(
+  model="us.anthropic.claude-sonnet-4-6",
+  region_name="us-west-2",
+)
+backend = AgentCoreSandbox(interpreter=interpreter)
+agent = create_deep_agent(
+    model=model,
+    backend=backend,
+    system_prompt="You are a coding assistant with sandbox access.",
+)
+
+try:
+    result = agent.invoke(
+        {
+            "messages": [
+                {"role": "user", "content": "Create and run a hello world script"}
+            ]
+        }
+    )
+    print(result["messages"][-1].content)
+finally:
+    interpreter.stop()
+```
+
+### File operations
+
+```python
+# Upload files
+backend.upload_files([
+    ("data.csv", b"name,value\nalice,42\nbob,17"),
+    ("analyze.py", b"import csv\nprint('ready')"),
+])
+
+# Download files
+results = backend.download_files(["data.csv"])
+for r in results:
+    if r.content is not None:
+        print(f"{r.path}: {r.content.decode()}")
+    else:
+        print(f"Failed: {r.path}: {r.error}")
+```
+
+## Session behavior
+
+AgentCore sessions cannot be reconnected after `interpreter.stop()` is called. Each `start()` creates a fresh, isolated MicroVM. Sessions auto-expire after a configurable timeout (default 15 minutes, maximum 8 hours).
+
+## Contributing
+
+See the [langchain-aws contributing guide](https://github.com/langchain-ai/langchain-aws/blob/main/.github/CONTRIBUTING.md).
+
+```bash
+cd libs/agentcore-codeinterpreter
+
+# Run unit tests (no network, no AWS credentials needed)
+make tests
+
+# Run linter
+make lint
+
+# Run integration tests (requires AWS credentials)
+make integration_tests
+```

langchain_agentcore_codeinterpreter-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+langchain_agentcore_codeinterpreter/__init__.py,sha256=5Q8uChJ-rUXR0QVEQcIfS1dbzvAOk7EC7L1twhVVZsU,191
+langchain_agentcore_codeinterpreter/sandbox.py,sha256=D_BjDRnw0704XgyRF9SAzv2savmewi3Fok1zg2kUQLY,9234
+langchain_agentcore_codeinterpreter-0.0.1.dist-info/METADATA,sha256=eHMBUMlXEgqMcMqlVUfLjmoqF5dvxrrW5YFabB0Yzr0,5676
+langchain_agentcore_codeinterpreter-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+langchain_agentcore_codeinterpreter-0.0.1.dist-info/licenses/LICENSE,sha256=TsZ-TKbmch26hJssqCJhWXyGph7iFLvyFBYAa3stBHg,1067
+langchain_agentcore_codeinterpreter-0.0.1.dist-info/RECORD,,

langchain_agentcore_codeinterpreter-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_agentcore_codeinterpreter-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.