fix: managed agents follow-ups - safety, observability, tests, CLI parity

src/praisonai-agents/praisonaiagents/managed/__init__.py

@@ -25,6 +25,7 @@
     ComputeConfig,
     InstanceInfo,
     InstanceStatus,
+    ManagedBackendProtocol,
 )
 
 __all__ = [
@@ -41,4 +42,5 @@
     "ComputeConfig",
     "InstanceInfo",
     "InstanceStatus",
+    "ManagedBackendProtocol",
 ]

src/praisonai-agents/praisonaiagents/managed/protocols.py

@@ -216,3 +216,131 @@ async def list_instances(self) -> List[InstanceInfo]:
             List of InstanceInfo for running instances.
         """
         ...
+
+
+@runtime_checkable
+class ManagedBackendProtocol(Protocol):
+    """Protocol for external managed agent backends.
+
+    Defines the contract between PraisonAI Agent's delegation layer
+    and any managed agent infrastructure provider (Anthropic Managed Agents, etc.).
+
+    The Core SDK defines *what* — this protocol.
+    The Wrapper implements *how* — the provider-specific adapter.
+
+    Lifecycle::
+
+        backend = SomeManagedBackend(config={...})
+        agent = Agent(name="coder", backend=backend)
+        result = agent.start("Write a script")  # delegates to backend.execute()
+
+    Implementations must handle:
+    - Agent/environment/session creation and caching
+    - Event streaming (agent.message, agent.tool_use, session.status_idle)
+    - Custom tool calls (agent.custom_tool_use → user.custom_tool_result)
+    - Tool confirmation (always_ask policy → user.tool_confirmation)
+    - Usage tracking (input_tokens, output_tokens)
+    - Session reset for multi-turn isolation
+    """
+
+    async def execute(self, prompt: str, **kwargs) -> str:
+        """Execute a prompt on managed infrastructure and return the full response.
+
+        This is the primary entry point called by Agent._delegate_to_backend().
+
+        Args:
+            prompt: The user message to send to the managed agent.
+            **kwargs: Provider-specific options (e.g., timeout, metadata).
+
+        Returns:
+            The agent's complete text response.
+        """
+        ...
+
+    async def stream(self, prompt: str, **kwargs):
+        """Stream a prompt response as text chunks.
+
+        Yields text fragments as the managed agent produces them.
+        Used when Agent is invoked with stream=True.
+
+        Args:
+            prompt: The user message.
+            **kwargs: Provider-specific options.
+
+        Yields:
+            Text chunks from the agent's response.
+        """
+        ...
+        yield ""  # type: ignore[misc]
+
+    def reset_session(self) -> None:
+        """Discard the cached session so the next execute() creates a fresh one.
+
+        The agent and environment remain cached for reuse.
+        """
+        ...
+
+    def reset_all(self) -> None:
+        """Discard all cached state (agent, environment, session, client).
+
+        Next execute() call will re-create everything from scratch.
+        """
+        ...
+
+    # ── Optional methods (default no-ops for backward compat) ──
+
+    def update_agent(self, **kwargs) -> None:
+        """Update an existing managed agent's configuration.
+
+        Allows changing system prompt, tools, model, etc. on a previously
+        created agent without recreating it.
+
+        Args:
+            **kwargs: Fields to update (system, tools, model, name, etc.).
+        """
+        ...
+
+    def interrupt(self) -> None:
+        """Send a user interrupt to the active session.
+
+        Signals the managed agent to stop its current work (equivalent to
+        ``user.interrupt`` event in the Anthropic API).
+        """
+        ...
+
+    def retrieve_session(self) -> Dict[str, Any]:
+        """Retrieve the current managed session's metadata and usage.
+
+        Standardized return schema::
+
+            {
+                "session_id": "sesn_01234",
+                "agent_id": "agent_01234", 
+                "environment_id": "env_01234",
+                "status": "idle" | "running" | "error",
+                "created_at": 1234567890.0,
+                "last_activity_at": 1234567890.0,
+                "usage": {
+                    "input_tokens": 150,
+                    "output_tokens": 75,
+                    "cache_creation_input_tokens": 0,
+                    "cache_read_input_tokens": 0
+                },
+                "metadata": {}
+            }
+
+        Returns:
+            Dict with standardized session info.
+        """
+        ...
+
+    def list_sessions(self, **kwargs) -> List[Dict[str, Any]]:
+        """List sessions for the current agent.
+
+        Args:
+            **kwargs: Provider-specific filters (limit, status, etc.).
+
+        Returns:
+            List of session summary dicts with same schema as retrieve_session().
+        """
+        ...

src/praisonai/praisonai/cli/commands/managed.py

@@ -532,6 +532,97 @@ def ids_restore(
         print(result)
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Delete commands for missing CLI operations (Fix A7)
+# ─────────────────────────────────────────────────────────────────────────────
+
+@sessions_app.command("delete")
+def sessions_delete(
+    session_id: str = typer.Argument(..., help="Session ID to delete"),
+    force: bool = typer.Option(False, "--force", help="Force delete without confirmation"),
+):
+    """Delete a managed session."""
+    if not force:
+        confirm = typer.confirm(f"Delete session {session_id}?")
+        if not confirm:
+            typer.echo("Cancelled.")
+            return
+
+    client = _get_client()
+    try:
+        # For Anthropic managed agents, delete via API
+        response = client.delete(f"/v1/agent_sessions/{session_id}")
+        typer.secho(f"Session {session_id} deleted", fg="green")
+    except Exception as e:
+        typer.secho(f"Failed to delete session: {e}", fg="red")
+
+
+@agents_app.command("delete")
+def agents_delete(
+    agent_id: str = typer.Argument(..., help="Agent ID to delete"),
+    force: bool = typer.Option(False, "--force", help="Force delete without confirmation"),
+):
+    """Delete a managed agent."""
+    if not force:
+        confirm = typer.confirm(f"Delete agent {agent_id}? This will also delete all its sessions.")
+        if not confirm:
+            typer.echo("Cancelled.")
+            return
+
+    client = _get_client()
+    try:
+        response = client.delete(f"/v1/agents/{agent_id}")
+        typer.secho(f"Agent {agent_id} deleted", fg="green")
+    except Exception as e:
+        typer.secho(f"Failed to delete agent: {e}", fg="red")
+
+
+@envs_app.command("update")
+def envs_update(
+    env_id: str = typer.Argument(..., help="Environment ID to update"),
+    name: Optional[str] = typer.Option(None, "--name", help="New environment name"),
+    description: Optional[str] = typer.Option(None, "--description", help="New environment description"),
+):
+    """Update a managed environment."""
+    if not name and not description:
+        typer.echo("Must specify at least --name or --description")
+        return
+
+    client = _get_client()
+    try:
+        data = {}
+        if name:
+            data["name"] = name
+        if description:
+            data["description"] = description
+
+        response = client.patch(f"/v1/environments/{env_id}", json=data)
+        typer.secho(f"Environment {env_id} updated", fg="green")
+        typer.echo(json.dumps(response.json(), indent=2))
+    except Exception as e:
+        typer.secho(f"Failed to update environment: {e}", fg="red")
+
+
+@envs_app.command("delete")
+def envs_delete(
+    env_id: str = typer.Argument(..., help="Environment ID to delete"),
+    force: bool = typer.Option(False, "--force", help="Force delete without confirmation"),
+):
+    """Delete a managed environment."""
+    if not force:
+        confirm = typer.confirm(f"Delete environment {env_id}? This may affect running agents.")
+        if not confirm:
+            typer.echo("Cancelled.")
+            return
+
+    client = _get_client()
+    try:
+        response = client.delete(f"/v1/environments/{env_id}")
+        typer.secho(f"Environment {env_id} deleted", fg="green")
+    except Exception as e:
+        typer.secho(f"Failed to delete environment: {e}", fg="red")
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Register sub-apps onto main app
 # ─────────────────────────────────────────────────────────────────────────────