feat: Fleet client

examples/fleet_env_example.py

@@ -0,0 +1,153 @@
+"""
+Example: Orchestrator + Agent loop using OpenEnv on Fleet.
+
+Demonstrates the split architecture:
+1. Orchestrator: Provisions environment, resets episodes (HTTP).
+2. Agent: Lists tools, calls tools (MCP).
+
+Prerequisites:
+  pip install "openenv-core[fleet]"
+  export FLEET_API_KEY="..."
+  export FLEET_ENV_KEY="..."  # e.g. "browser-env" or your custom env
+"""
+
+import asyncio
+import os
+import random
+import sys
+from typing import Any, Dict, List, Sequence
+
+# Ensure we can import from src/ if running from repo root
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src")))
+
+try:
+    # `openenv` installs top-level packages like `envs`, `core`, etc.
+    # This example also prepends `src/` above so it works from a repo checkout.
+    from envs.fleet_env import FleetEnvClient
+except ImportError as e:
+    raise ImportError(
+        "Could not import `envs.fleet_env`. "
+        "Run from the repo root, or install OpenEnv in editable mode: "
+        "`python -m pip install -e '.[fleet]'`."
+    ) from e
+
+def get_openai_tool_param_enum(tool_def: Dict[str, Any], param_name: str) -> List[str]:
+    """Extract an enum list for a parameter from an OpenAI 'tools' dict."""
+    schema = tool_def.get("function", {}).get("parameters", {})
+    if not isinstance(schema, dict):
+        return []
+    props = schema.get("properties", {})
+    if not isinstance(props, dict):
+        return []
+    param_spec = props.get(param_name, {})
+    if not isinstance(param_spec, dict):
+        return []
+    enum = param_spec.get("enum", [])
+    return enum if isinstance(enum, list) else []
+
+SAFE_COMPUTER_ACTION_PREFERENCE: Sequence[str] = ("screenshot", "wait", "cursor_position")
+
+
+def pick_safe_computer_action(tool_def: Dict[str, Any]) -> str:
+    """Pick a non-destructive default action for the Fleet 'computer' tool.
+
+    Prefer safe actions like screenshot/wait, falling back to first enum.
+    """
+    actions = get_openai_tool_param_enum(tool_def, "action")
+    if not actions:
+        raise ValueError("Tool 'computer' has no available actions in schema.")
+
+    action_set = set(actions)
+    safe_available = [a for a in SAFE_COMPUTER_ACTION_PREFERENCE if a in action_set]
+    if safe_available:
+        return random.choice(safe_available)
+    return actions[0]
+
+def main():
+    api_key = os.environ.get("FLEET_API_KEY")
+
+    # 1. Get env_key from args or env var
+    env_key = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("FLEET_ENV_KEY")
+
+    if not api_key or not env_key:
+        print("Usage: python fleet_env_example.py <env_key>")
+        print("   or: export FLEET_ENV_KEY=... && python fleet_env_example.py")
+        raise ValueError("Please set FLEET_API_KEY and provide an env_key.")
+
+    print(f"Provisioning Fleet environment: {env_key}...")
+
+    # 1. Provision & Split Handles (Synchronous)
+    # This must be run outside of an async loop because it manages its own loop.
+    try:
+        orch, tools = FleetEnvClient.from_fleet(
+            api_key=api_key,
+            env_key=env_key,
+            ttl_seconds=600,  # 10 min TTL
+        )
+    except Exception as e:
+        raise ValueError(f"Failed to provision environment: {e}")
+
+
+    try:
+        # Run the async agent loop
+        asyncio.run(agent_loop(orch, tools))
+    except BaseException as e:
+        print(f"\n❌ Agent loop failed: {e}")
+    finally:
+        # 5. Cleanup (Synchronous)
+        print("\nOrchestrator: Closing environment...")
+        orch.close()
+        print("Done.")
+
+
+async def agent_loop(orch, tools):
+    # 2. Orchestration: Start Episode (HTTP calls, sync method but we wrap or call directly)
+    # orch.reset() is sync (requests), so it blocks the loop briefly. That's fine for this example.
+    print("Orchestrator: Resetting environment...")
+    obs = orch.reset()
+    print(f"Reset complete. Initial observation keys: {list(obs.observation.metadata.keys())}")
+
+    # 3. Agent: Discover Tools (Async)
+    print("\nAgent: Discovering tools...")
+    listed = await tools.list_tools()
+    tool_defs = listed.tools
+    print(f"Available tools ({len(tool_defs)}): {[t['function']['name'] for t in tool_defs]}")
+    # Print the derived schema payloads (mirrors MCP Tool.inputSchema content, but OpenAI-shaped)
+    print([t["function"]["parameters"] for t in tool_defs])
+
+    if not tool_defs:
+        print("No MCP tools available (all MCP endpoints may be down).")
+        return
+
+    # 4. Agent: Call a Tool
+    target_tool_name = "computer"
+    target_def = next((t for t in tool_defs if t["function"]["name"] == target_tool_name), None)
+
+    if not target_def:
+        print(f"Tool '{target_tool_name}' not found, picking first available.")
+        target_def = tool_defs[0]
+        target_tool_name = target_def["function"]["name"]
+
+    print(f"\nTarget Tool: {target_tool_name}")
+    # Inspect schema to construct params (in a real agent, the LLM does this)
+    # schema = target_def["function"]["parameters"]
+    # print(f"Schema: {json.dumps(schema, indent=2)}")
+
+    params = {}
+    if target_tool_name == "computer":
+        # Choose a supported action from the schema (safe default).
+        params = {"action": pick_safe_computer_action(target_def)}
+
+    print(f"\nAgent: Calling tool '{target_tool_name}' with {params}...")
+    result = await tools.call_tool(target_tool_name, params)
+
+
+    # Result is typically a list of MCP content objects (TextContent/ImageContent)
+    # We'll just print a summary.
+    print("Agent: Tool execution result received.")
+    print(f"{result=}")
+
+
+if __name__ == "__main__":
+    main()
+

pyproject.toml

@@ -26,6 +26,12 @@ dependencies = [
     "tomli-w>=1.2.0"
 ]
 
+[project.optional-dependencies]
+fleet = [
+    "mcp>=1.0.0",
+    "fleet-python>=0.2.79",
+]
+
 [project.scripts]
 openenv = "openenv_cli.__main__:main"
 
@@ -39,6 +45,9 @@ include-package-data = true
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
 [tool.coverage.run]
 omit = [
     "openenv_cli/templates/**",

src/envs/fleet_env/README.md

@@ -0,0 +1,123 @@
+### Fleet environments
+
+This integration lets you run Fleet environments through OpenEnv, simplifying the interaction and adhering to OpenEnv standards; keeping **orchestration** and **agent actions** separate.
+
+- **Orchestration (HTTP)**: reset / step / state (episode + lifecycle control)
+- **Agent actions (MCP)**: tools/list + tools/call (what the agent can do)
+
+That boundary matches **RFC 001** (split planes) and lines up with **RFC 003**’s “tool-call actions”.
+If you want the longer-form design background, see:
+
+- **RFC 001**: [`rfcs/001-abstractions.md`](../../../rfcs/001-abstractions.md)
+- **RFC 003**: [`rfcs/003-mcp-support.md`](../../../rfcs/003-mcp-support.md)
+
+### What this is *not* (container/provider abstraction)
+
+This Fleet integration is intentionally **not yet** a “container runtime” abstraction (no Docker provider, no local container lifecycle).
+In particular, there is **no local Dockerized setup** where you spin up an “env server” container alongside an “env” container; Fleet hosts the runtime remotely (HTTP env server + MCP service), and the client connects to it.
+
+Fleet provisions and runs the environment remotely; on the client side we just hold two handles:
+
+- `FleetEnvClient` for the HTTP orchestration plane
+- `FleetMCPTools` for the MCP agent plane
+
+### Architecture (one picture)
+
+```mermaid
+flowchart TB
+  subgraph Client["OpenEnv client (local)"]
+    Agent["Agent / Policy"]
+    Orch["FleetEnvClient (HTTP)"]
+    Tools["FleetMCPTools (MCP)"]
+  end
+
+  subgraph Runtime["Fleet runtime (remote)"]
+    HTTP["Instance Manager HTTP API"]
+    MCP["MCP service"]
+  end
+
+  Orch -- reset/step/state --> HTTP
+  Agent -- list_tools/call_tool --> Tools
+  Tools <-- streamable HTTP --> MCP
+```
+
+### What FleetMCPTools
+
+Fleet currently exposes **more than one MCP endpoint** (commonly `api/v1/mcp` and `mcp` - Later we will abstarct this to the Fleet server).
+`FleetMCPTools` handles that so your agent code doesn’t need to care:
+
+- **Union tools**: `await tools.list_tools()` returns a `ListToolsAction` where `.tools` is the union of tools across endpoints.
+- **OpenAI-friendly format**: `.tools` is already in OpenAI “tools” dict format (via `convert_tool_format()`).
+- **Route calls**: `await tools.call_tool(name, args)` routes to the endpoint that owns `name` (cached after discovery).
+
+
+### Pseudocode
+
+
+```python
+class FleetEnvClient(HTTPEnvClient):
+    @classmethod
+    def from_fleet(cls, api_key: str, env_key: str, **kwargs):
+        # 1) Provision a remote instance via Fleet SDK
+        env = Fleet(api_key=api_key).make(env_key=env_key, image_type="mcp", **kwargs)
+
+        # 2) Orchestrator handle talks to the Instance Manager (HTTP)
+        orch = cls(
+            base_url=env.urls.manager.api,
+            default_headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+        # 3) Agent handle talks to MCP (may be multiple endpoints today)
+        mcp_urls = (
+            f"{env.urls.root}api/v1/mcp",
+            f"{env.urls.root}mcp",
+        )
+        tools = FleetMCPTools(api_key=api_key, mcp_urls=mcp_urls)
+
+        return orch, tools
+```
+
+### Quickstart
+
+- Install: `pip install "openenv-core[fleet]"`
+- Set: `export FLEET_API_KEY="..."`
+- Run: `python examples/fleet_env_example.py <env_key>`
+
+### Walkthrough (what the example is doing)
+
+See `examples/fleet_env_example.py`.
+
+1. **Provision** a remote env on Fleet:
+   - `orch, tools = FleetEnvClient.from_fleet(...)`
+2. **Reset** the episode via HTTP:
+   - `obs = orch.reset()`
+3. **Discover tools** via MCP:
+   - `listed = await tools.list_tools()`
+   - `tool_defs = listed.tools`
+   - Each entry in `tool_defs` has `{"type": "function", "function": {"name": ..., "parameters": ...}}`
+4. **Call a tool** (the example picks a “safe” action from the schema and calls `computer`)
+
+Here’s a real run (trimmed) so you know what “healthy” looks like:
+
+```text
+Provisioning Fleet environment: amazon...
+Orchestrator: Resetting environment...
+Reset complete. Initial observation keys: []
+
+Agent: Discovering tools...
+Available tools (1): ['computer']
+[{'type': 'object', 'properties': {'action': {'enum': ['screenshot', ..., 'cursor_position'], 'type': 'string'}, ...}, 'required': ['action']}]
+
+Target Tool: computer
+Agent: Calling tool 'computer' with {'action': 'cursor_position'}...
+Agent: Tool execution result received.
+result=CallToolResult(... structuredContent={'result': {'output': 'X=683,Y=384', ...}})
+```
+
+### TODOs
+
+- **MCP endpoint abstraction**: stop hardcoding `("api/v1/mcp", "mcp")` and discover endpoints (or accept a single unified endpoint when Fleet provides one).
+- **Reset inconsistencies**: some env keys don’t behave consistently on `/reset` (needs better error reporting + a compatibility note per env type).
+- **Support for all OpenEnv environments**: Starting with OpenEnv, we want to support any backend to run environments at scale.
+- **Retries / backoff**: MCP list/call should have bounded retries and clearer failure modes when one endpoint is down.
+- **GA access**: GA the Fleet platform. 

src/envs/fleet_env/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Fleet Environment - client-side adapter for Fleet-hosted MCP environments."""
+
+from .client import FleetEnvClient
+from .mcp_tools import FleetMCPTools
+from .models import CallToolAction, ListToolsAction
+
+__all__ = ["FleetEnvClient", "FleetMCPTools", "ListToolsAction", "CallToolAction"]
+
+