feat(tools): add Fly.io Sprites command execution tool

docs/docs.json

@@ -306,7 +306,8 @@
                           "edge/en/tools/ai-ml/ragtool",
                           "edge/en/tools/ai-ml/codeinterpretertool",
                           "edge/en/tools/ai-ml/daytona",
-                          "edge/en/tools/ai-ml/e2bsandboxtools"
+                          "edge/en/tools/ai-ml/e2bsandboxtools",
+                          "edge/en/tools/ai-ml/spritestool"
                         ]
                       },
                       {
@@ -14761,7 +14762,8 @@
                           "edge/pt-BR/tools/ai-ml/langchaintool",
                           "edge/pt-BR/tools/ai-ml/ragtool",
                           "edge/pt-BR/tools/ai-ml/codeinterpretertool",
-                          "edge/pt-BR/tools/ai-ml/daytona"
+                          "edge/pt-BR/tools/ai-ml/daytona",
+                          "edge/pt-BR/tools/ai-ml/spritestool"
                         ]
                       },
                       {
@@ -28217,7 +28219,8 @@
                           "edge/ko/tools/ai-ml/llamaindextool",
                           "edge/ko/tools/ai-ml/langchaintool",
                           "edge/ko/tools/ai-ml/ragtool",
-                          "edge/ko/tools/ai-ml/codeinterpretertool"
+                          "edge/ko/tools/ai-ml/codeinterpretertool",
+                          "edge/ko/tools/ai-ml/spritestool"
                         ]
                       },
                       {
@@ -42118,7 +42121,8 @@
                           "edge/ar/tools/ai-ml/llamaindextool",
                           "edge/ar/tools/ai-ml/langchaintool",
                           "edge/ar/tools/ai-ml/ragtool",
-                          "edge/ar/tools/ai-ml/codeinterpretertool"
+                          "edge/ar/tools/ai-ml/codeinterpretertool",
+                          "edge/ar/tools/ai-ml/spritestool"
                         ]
                       },
                       {

docs/edge/ar/tools/ai-ml/spritestool.mdx

@@ -0,0 +1,65 @@
+---
+title: أداة تنفيذ Fly.io Sprites
+description: امنح وكلاء CrewAI وصولاً إلى shell داخل Fly.io Sprite موجود ودائم.
+icon: terminal
+mode: "wide"
+---
+
+## نظرة عامة
+
+تنفّذ `SpritesExecTool` أوامر shell داخل [Fly.io Sprite](https://sprites.dev) موجود، باستخدام SDK الرسمي لـ Python. تبقى الملفات بين الاستدعاءات. يبدأ كل استدعاء جلسة Bash جديدة، لذلك لا تنتقل متغيرات shell وتغييرات مجلد العمل إلى الاستدعاء التالي.
+
+يدير المستدعي دورة حياة Sprite: لا تنشئ هذه الأداة Sprites ولا تحذفها.
+
+## التثبيت والمصادقة
+
+ثبّت الاعتماد الاختياري:
+
+```shell
+uv add "crewai-tools[sprites]"
+```
+
+أنشئ Sprite باستخدام [Sprites CLI](https://docs.sprites.dev/cli/) قبل استخدام الأداة. اضبط `SPRITE_TOKEN` في بيئة عملية CrewAI على رمز مخوّل للوصول إلى ذلك Sprite، أو مرّره عبر `api_key` عند إنشاء الأداة. الرمز ليس وسيطاً للوكيل، ويُستبعد من تسلسل الأداة، ولا يُحقن في الأوامر البعيدة.
+
+## الاستخدام
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_tools import SpritesExecTool
+
+tool = SpritesExecTool(sprite_name="crew-workspace", timeout=60)
+agent = Agent(
+    role="Python developer",
+    goal="Run and verify Python programs in the provided Fly.io Sprite",
+    backstory="You check program output and report failures accurately.",
+    tools=[tool],
+)
+task = Task(
+    description="Use the Sprite to print the sum of the integers from 1 to 100.",
+    expected_output="The command used, its exit code, and the computed sum.",
+    agent=agent,
+)
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+يتطلب المثال أيضاً بيانات اعتماد موفّر LLM الذي تختاره. للاستدعاء المباشر دون LLM:
+
+```python
+result = tool.run(command="python -c 'print(sum(range(1, 101)))'")
+# {"exit_code": 0, "stdout": "5050\n", "stderr": "",
+#  "stdout_truncated": False, "stderr_truncated": False}
+```
+
+## الإعدادات والوسائط
+
+اضبط `sprite_name` (مطلوب)، و`api_key` (يستخدم `SPRITE_TOKEN` افتراضياً)، و`timeout` (60 ثانية افتراضياً، أكبر من 0 وبحد أقصى 300)، و`max_output_chars` (20,000 لكل تدفق افتراضياً) في الأداة. يقدّم الوكيل `command` و`cwd` الاختياري فقط، ويُفسّران داخل Sprite.
+
+تتضمن النتائج `exit_code` و`stdout` و`stderr` بترميز UTF-8 (تُستبدل البايتات غير الصالحة)، ومؤشر اقتطاع لكل تدفق. تُعاد رموز الخروج غير الصفرية إلى الوكيل ولا تُعامل كأخطاء نقل. تستخدم الاستدعاءات غير المتزامنة `await tool.arun(command="...")`. لا تُخزّن النتائج مؤقتاً افتراضياً لأن الأوامر قد تغيّر الحالة الدائمة.
+
+## السلامة والحدود
+
+- تتمتع الأوامر بوصول إلى shell ويمكنها تعديل البيانات أو حذفها والوصول إلى شبكة Sprite وبيانات اعتماده. استخدم Sprite مخصصاً يحتوي فقط على البيانات والصلاحيات التي يحتاجها الوكيل. تثبيت اسم Sprite ليس حداً للتفويض على الخادم.
+- يحدّد `timeout` مدة انتظار العميل؛ لكنه **لا** يضمن إنهاء العملية البعيدة. يغلق الإلغاء غير المتزامن الاتصال المحلي دون ترك خيط عامل في منفّذ المهام قيد التشغيل، لكنه لا يضمن أيضاً إنهاء العملية البعيدة. بعد الإلغاء أو انتهاء المهلة أو فشل الاتصال، افحص Sprite قبل إعادة أمر له آثار جانبية.
+- يحتفظ جامع الخرج بحد أقصى `max_output_chars` حرفاً لكل تدفق، مع فك ترميز UTF-8 تدريجياً. يُتخلّص من الخرج الزائد قبل تراكمه في SDK، مع مواصلة قراءة الاتصال حتى خروج الأمر أو انتهاء المهلة. يحدّ ذلك من الخرج المحتفظ به، وليس من حركة الشبكة أو أعباء النقل لكل إطار. وجّه الخرج المطوّل إلى ملفات داخل Sprite.
+- لا تُمرّر متغيرات بيئة المضيف تلقائياً. تبقى الملفات إلى أن تديرها أو تزيلها بنفسك.

docs/edge/en/tools/ai-ml/spritestool.mdx

@@ -0,0 +1,65 @@
+---
+title: Fly.io Sprites Exec Tool
+description: Give CrewAI agents shell access to an existing, persistent Fly.io Sprite.
+icon: terminal
+mode: "wide"
+---
+
+## Overview
+
+`SpritesExecTool` runs shell commands in an existing [Fly.io Sprite](https://sprites.dev), using the official Python SDK. Files persist across calls. Each call starts a new Bash shell, so shell variables and working-directory changes do not carry over.
+
+The caller manages the Sprite lifecycle: this tool neither creates nor deletes Sprites.
+
+## Installation and authentication
+
+Install the optional dependency:
+
+```shell
+uv add "crewai-tools[sprites]"
+```
+
+Create a Sprite using the [Sprites CLI](https://docs.sprites.dev/cli/) before using the tool. Set `SPRITE_TOKEN` in the CrewAI process environment to a token authorized for that Sprite, or pass it as `api_key` when constructing the tool. The token is not an agent argument, is excluded from tool serialization, and is not injected into remote commands.
+
+## Usage
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_tools import SpritesExecTool
+
+tool = SpritesExecTool(sprite_name="crew-workspace", timeout=60)
+agent = Agent(
+    role="Python developer",
+    goal="Run and verify Python programs in the provided Fly.io Sprite",
+    backstory="You check program output and report failures accurately.",
+    tools=[tool],
+)
+task = Task(
+    description="Use the Sprite to print the sum of the integers from 1 to 100.",
+    expected_output="The command used, its exit code, and the computed sum.",
+    agent=agent,
+)
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+The example also requires your chosen LLM provider's credentials. For a direct call without an LLM:
+
+```python
+result = tool.run(command="python -c 'print(sum(range(1, 101)))'")
+# {"exit_code": 0, "stdout": "5050\n", "stderr": "",
+#  "stdout_truncated": False, "stderr_truncated": False}
+```
+
+## Configuration and arguments
+
+Configure `sprite_name` (required), `api_key` (defaults to `SPRITE_TOKEN`), `timeout` (default 60 seconds, greater than 0 and at most 300), and `max_output_chars` (default 20,000 per stream) on the tool. The agent only supplies `command` and optional `cwd`, both interpreted inside the Sprite.
+
+Results include `exit_code`, UTF-8 `stdout` and `stderr` (invalid bytes are replaced), and a truncation flag for each stream. Non-zero exits are returned to the agent, not treated as transport failures. Async calls use `await tool.arun(command="...")`. Results are not cached by default because commands can change persistent state.
+
+## Safety and limits
+
+- Commands have shell access and can modify or delete data and access the Sprite's network and credentials. Use a dedicated Sprite with only the data and permissions the agent needs. Binding a Sprite name is not a server-side authorization boundary.
+- `timeout` limits how long the client waits; it does **not** guarantee remote process termination. Async cancellation closes the local connection without leaving an executor worker running, but also does not guarantee remote termination. After cancellation, a timeout, or a connection failure, inspect the Sprite before retrying a command with side effects.
+- Output collection retains at most `max_output_chars` characters per stream, decoding UTF-8 incrementally. Excess output is discarded before SDK accumulation while the connection is drained until command exit or timeout. This bounds retained output, not network traffic or per-frame transport overhead. Redirect verbose output to files in the Sprite.
+- No host environment variables are forwarded automatically. Files remain until you manage or remove them yourself.

docs/edge/ko/tools/ai-ml/spritestool.mdx

@@ -0,0 +1,65 @@
+---
+title: Fly.io Sprites 실행 도구
+description: CrewAI 에이전트에 기존의 영구 Fly.io Sprite 셸 접근 권한을 제공합니다.
+icon: terminal
+mode: "wide"
+---
+
+## 개요
+
+`SpritesExecTool`은 공식 Python SDK를 사용하여 기존 [Fly.io Sprite](https://sprites.dev)에서 셸 명령을 실행합니다. 파일은 호출 간에 유지됩니다. 각 호출은 새로운 Bash 셸을 시작하므로 셸 변수와 작업 디렉터리 변경 사항은 다음 호출로 이어지지 않습니다.
+
+Sprite의 수명 주기는 호출자가 관리합니다. 이 도구는 Sprite를 생성하거나 삭제하지 않습니다.
+
+## 설치 및 인증
+
+선택적 의존성을 설치하세요.
+
+```shell
+uv add "crewai-tools[sprites]"
+```
+
+도구를 사용하기 전에 [Sprites CLI](https://docs.sprites.dev/cli/)로 Sprite를 생성하세요. CrewAI 프로세스 환경의 `SPRITE_TOKEN`에 해당 Sprite에 접근할 수 있는 토큰을 설정하거나, 도구를 생성할 때 `api_key`로 전달하세요. 토큰은 에이전트 인수가 아니며, 도구 직렬화에서 제외되고 원격 명령에 주입되지 않습니다.
+
+## 사용법
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_tools import SpritesExecTool
+
+tool = SpritesExecTool(sprite_name="crew-workspace", timeout=60)
+agent = Agent(
+    role="Python developer",
+    goal="Run and verify Python programs in the provided Fly.io Sprite",
+    backstory="You check program output and report failures accurately.",
+    tools=[tool],
+)
+task = Task(
+    description="Use the Sprite to print the sum of the integers from 1 to 100.",
+    expected_output="The command used, its exit code, and the computed sum.",
+    agent=agent,
+)
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+이 예제에는 선택한 LLM 제공업체의 인증 정보도 필요합니다. LLM 없이 직접 호출하려면 다음과 같이 사용하세요.
+
+```python
+result = tool.run(command="python -c 'print(sum(range(1, 101)))'")
+# {"exit_code": 0, "stdout": "5050\n", "stderr": "",
+#  "stdout_truncated": False, "stderr_truncated": False}
+```
+
+## 설정 및 인수
+
+도구에서 `sprite_name`(필수), `api_key`(기본값은 `SPRITE_TOKEN`), `timeout`(기본값 60초, 0보다 크고 최대 300), `max_output_chars`(스트림당 기본값 20,000)를 설정하세요. 에이전트는 `command`와 선택적 `cwd`만 제공하며, 둘 다 Sprite 내부에서 해석됩니다.
+
+결과에는 `exit_code`, UTF-8 `stdout` 및 `stderr`(잘못된 바이트는 대체됨), 각 스트림의 잘림 여부가 포함됩니다. 0이 아닌 종료 코드는 전송 실패로 처리하지 않고 에이전트에 반환합니다. 비동기 호출은 `await tool.arun(command="...")`을 사용합니다. 명령이 영구 상태를 변경할 수 있으므로 기본적으로 결과를 캐시하지 않습니다.
+
+## 안전 및 제한 사항
+
+- 명령은 셸 접근 권한을 가지며 데이터를 수정하거나 삭제하고 Sprite의 네트워크 및 인증 정보에 접근할 수 있습니다. 에이전트에 필요한 데이터와 권한만 있는 전용 Sprite를 사용하세요. Sprite 이름을 고정하는 것은 서버 측 권한 경계가 아닙니다.
+- `timeout`은 클라이언트의 대기 시간만 제한하며 원격 프로세스 종료를 **보장하지 않습니다**. 비동기 취소는 실행 중인 executor 작업 스레드를 남기지 않고 로컬 연결을 닫지만 원격 프로세스 종료를 보장하지는 않습니다. 취소, 시간 초과 또는 연결 실패 후에는 부수 효과가 있는 명령을 다시 실행하기 전에 Sprite를 확인하세요.
+- 출력 수집기는 UTF-8을 점진적으로 디코딩하며 스트림당 최대 `max_output_chars`개의 문자만 보관합니다. 초과 출력은 SDK에 누적되기 전에 버리지만, 명령이 종료되거나 시간이 초과될 때까지 연결에서 계속 읽습니다. 이는 보관되는 출력을 제한하며 네트워크 트래픽이나 프레임별 전송 오버헤드는 제한하지 않습니다. 많은 출력은 Sprite 내부 파일로 리디렉션하세요.
+- 호스트 환경 변수는 자동 전달되지 않습니다. 파일은 직접 관리하거나 제거할 때까지 유지됩니다.

docs/edge/pt-BR/tools/ai-ml/spritestool.mdx

@@ -0,0 +1,65 @@
+---
+title: Ferramenta de execução do Fly.io Sprites
+description: Dê aos agentes CrewAI acesso ao shell de um Fly.io Sprite existente e persistente.
+icon: terminal
+mode: "wide"
+---
+
+## Visão geral
+
+`SpritesExecTool` executa comandos de shell em um [Fly.io Sprite](https://sprites.dev) existente usando o SDK oficial de Python. Os arquivos persistem entre chamadas. Cada chamada inicia um novo shell Bash, portanto variáveis de shell e alterações no diretório de trabalho não são mantidas.
+
+O chamador gerencia o ciclo de vida do Sprite: esta ferramenta não cria nem exclui Sprites.
+
+## Instalação e autenticação
+
+Instale a dependência opcional:
+
+```shell
+uv add "crewai-tools[sprites]"
+```
+
+Crie um Sprite usando a [CLI do Sprites](https://docs.sprites.dev/cli/) antes de usar a ferramenta. Defina `SPRITE_TOKEN` no ambiente do processo CrewAI com um token autorizado para esse Sprite ou passe-o como `api_key` ao construir a ferramenta. O token não é um argumento do agente, é excluído da serialização da ferramenta e não é injetado nos comandos remotos.
+
+## Uso
+
+```python
+from crewai import Agent, Crew, Task
+from crewai_tools import SpritesExecTool
+
+tool = SpritesExecTool(sprite_name="crew-workspace", timeout=60)
+agent = Agent(
+    role="Python developer",
+    goal="Run and verify Python programs in the provided Fly.io Sprite",
+    backstory="You check program output and report failures accurately.",
+    tools=[tool],
+)
+task = Task(
+    description="Use the Sprite to print the sum of the integers from 1 to 100.",
+    expected_output="The command used, its exit code, and the computed sum.",
+    agent=agent,
+)
+crew = Crew(agents=[agent], tasks=[task])
+result = crew.kickoff()
+```
+
+O exemplo também requer as credenciais do provedor de LLM escolhido. Para uma chamada direta sem LLM:
+
+```python
+result = tool.run(command="python -c 'print(sum(range(1, 101)))'")
+# {"exit_code": 0, "stdout": "5050\n", "stderr": "",
+#  "stdout_truncated": False, "stderr_truncated": False}
+```
+
+## Configuração e argumentos
+
+Configure `sprite_name` (obrigatório), `api_key` (usa `SPRITE_TOKEN` por padrão), `timeout` (padrão de 60 segundos, maior que 0 e no máximo 300) e `max_output_chars` (padrão de 20.000 por fluxo) na ferramenta. O agente fornece apenas `command` e o `cwd` opcional, ambos interpretados dentro do Sprite.
+
+Os resultados incluem `exit_code`, `stdout` e `stderr` em UTF-8 (bytes inválidos são substituídos) e um indicador de truncamento para cada fluxo. Códigos de saída diferentes de zero são retornados ao agente, não tratados como falhas de transporte. Chamadas assíncronas usam `await tool.arun(command="...")`. Por padrão, os resultados não são armazenados em cache porque os comandos podem alterar o estado persistente.
+
+## Segurança e limites
+
+- Os comandos têm acesso ao shell e podem modificar ou excluir dados e acessar a rede e as credenciais do Sprite. Use um Sprite dedicado com apenas os dados e permissões necessários ao agente. Fixar um nome de Sprite não é um limite de autorização no servidor.
+- `timeout` limita o tempo de espera do cliente; **não** garante o encerramento do processo remoto. O cancelamento assíncrono fecha a conexão local sem deixar uma thread do executor em execução, mas também não garante o encerramento remoto. Após um cancelamento, timeout ou falha de conexão, inspecione o Sprite antes de repetir um comando com efeitos colaterais.
+- A coleta de saída retém no máximo `max_output_chars` caracteres por fluxo, decodificando UTF-8 incrementalmente. A saída excedente é descartada antes de se acumular no SDK, enquanto a conexão continua sendo lida até o comando terminar ou ocorrer um timeout. Isso limita a saída retida, não o tráfego de rede nem a sobrecarga de transporte por frame. Redirecione saídas extensas para arquivos no Sprite.
+- Nenhuma variável de ambiente do host é encaminhada automaticamente. Os arquivos permanecem até que você os gerencie ou remova.

lib/crewai-tools/pyproject.toml

@@ -26,6 +26,9 @@ Documentation = "https://docs.crewai.com"
 
 
 [project.optional-dependencies]
+sprites = [
+    "sprites-py>=0.6.0,<0.7",
+]
 scrapfly-sdk = [
     "scrapfly-sdk>=0.8.19",
 ]

lib/crewai-tools/src/crewai_tools/__init__.py

@@ -197,6 +197,7 @@
     SnowflakeSearchTool,
 )
 from crewai_tools.tools.spider_tool.spider_tool import SpiderTool
+from crewai_tools.tools.sprites_tool import SpritesExecTool
 from crewai_tools.tools.stagehand_tool.stagehand_tool import StagehandTool
 from crewai_tools.tools.tavily_extractor_tool.tavily_extractor_tool import (
     TavilyExtractorTool,
@@ -322,6 +323,7 @@
     "SnowflakeConfig",
     "SnowflakeSearchTool",
     "SpiderTool",
+    "SpritesExecTool",
     "StagehandTool",
     "TXTSearchTool",
     "TavilyExtractorTool",

lib/crewai-tools/src/crewai_tools/tools/__init__.py

@@ -184,6 +184,7 @@
     SnowflakeSearchToolInput,
 )
 from crewai_tools.tools.spider_tool.spider_tool import SpiderTool
+from crewai_tools.tools.sprites_tool import SpritesExecTool
 from crewai_tools.tools.stagehand_tool.stagehand_tool import StagehandTool
 from crewai_tools.tools.tavily_extractor_tool.tavily_extractor_tool import (
     TavilyExtractorTool,
@@ -305,6 +306,7 @@
     "SnowflakeSearchTool",
     "SnowflakeSearchToolInput",
     "SpiderTool",
+    "SpritesExecTool",
     "StagehandTool",
     "TXTSearchTool",
     "TavilyExtractorTool",