@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/scripts/codegen/generate_models.py

@@ -109,21 +109,35 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
             str(tokens_limit) if tokens_limit is not None else "None"
         )
 
-        lines.extend(
-            [
-                f"{const_name} = AIModel(",
-                f'    id="{spec["id"]}",',
-                f'    version="{spec["version"]}",',
-                f'    name="{spec["name"]}",',
-                f'    description="{spec.get("description", "")}",',
-                f'    provider="{spec["provider"]}",',
-                f"    default={spec.get('default', False)},",
-                f"    required_env_vars={env_vars_formatted},",
-                f"    tokens_limit={tokens_limit_formatted},",
-                ")",
-                "",
-            ]
-        )
+        model_lines = [
+            f"{const_name} = AIModel(",
+            f'    id="{spec["id"]}",',
+            f'    version="{spec["version"]}",',
+            f'    name="{spec["name"]}",',
+            f'    description="{spec.get("description", "")}",',
+            f'    provider="{spec["provider"]}",',
+            f"    default={spec.get('default', False)},",
+            # What is worth offering today, as distinct from what the platform
+            # knows how to talk to.
+            f"    available={spec.get('available', False)},",
+            f"    required_env_vars={env_vars_formatted},",
+            f"    tokens_limit={tokens_limit_formatted},",
+        ]
+
+        # Local-model fields, emitted only when set so hosted models stay terse.
+        if spec.get("local"):
+            model_lines.append("    local=True,")
+        if spec.get("base_url"):
+            model_lines.append(f'    base_url="{spec["base_url"]}",')
+        if spec.get("api_key_env"):
+            model_lines.append(f'    api_key_env="{spec["api_key_env"]}",')
+        capabilities = spec.get("capabilities") or []
+        if capabilities:
+            formatted = "[" + ", ".join(f'"{c}"' for c in capabilities) + "]"
+            model_lines.append(f"    capabilities={formatted},")
+
+        model_lines.extend([")", ""])
+        lines.extend(model_lines)
 
     # Generate catalog dictionary
     lines.extend(
@@ -304,10 +318,21 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
             f"  description: '{description}',",
             f"  provider: '{spec['provider']}',",
             f"  default: {str(spec.get('default', False)).lower()},",
+            f"  available: {str(spec.get('available', False)).lower()},",
             f"  requiredEnvVars: {env_vars_formatted},",
         ]
         if tokens_limit is not None:
             model_lines.append(f"  tokensLimit: {tokens_limit},")
+        if spec.get("local"):
+            model_lines.append("  local: true,")
+        if spec.get("base_url"):
+            model_lines.append(f"  baseUrl: '{spec['base_url']}',")
+        if spec.get("api_key_env"):
+            model_lines.append(f"  apiKeyEnv: '{spec['api_key_env']}',")
+        capabilities = spec.get("capabilities") or []
+        if capabilities:
+            formatted = "[" + ", ".join(f"'{c}'" for c in capabilities) + "]"
+            model_lines.append(f"  capabilities: {formatted},")
         model_lines.extend(
             [
                 "};",

package/scripts/codegen/generate_sandbox_agents.py

@@ -13,104 +13,118 @@ from __future__ import annotations
 import argparse
 from pathlib import Path
 
-VARIANTS: tuple[str, ...] = (
-    "eval",
-    "jupyter",
-    "docker",
-    "datalayer",
-    "colab",
-    "kaggle",
-    "monty",
-    "modal",
-)
-
-
-def _emoji_for_variant(variant: str) -> str:
-    mapping = {
-        "eval": "A",
-        "jupyter": "B",
-        "docker": "C",
-        "datalayer": "D",
-        "colab": "E",
-        "kaggle": "H",
-        "monty": "F",
-        "modal": "G",
-    }
-    return mapping.get(variant, "A")
+# Variant → the short key its spec goes by, so the ids stay the ones the
+# examples and the code-sandboxes capacity plugins already name.
+VARIANTS: dict[str, str] = {
+    "eval": "eval",
+    "jupyter-server": "jupyter",
+    "docker": "docker",
+    "datalayer": "datalayer",
+    "google-colab": "colab",
+    "kaggle": "kaggle",
+    "monty": "monty",
+    "modal": "modal",
+}
+
+_TITLES = {
+    "eval": "Eval",
+    "jupyter-server": "Jupyter",
+    "docker": "Docker",
+    "datalayer": "Datalayer",
+    "google-colab": "Colab",
+    "kaggle": "Kaggle",
+    "monty": "Monty",
+    "modal": "Modal",
+}
+
+_WHERE = {
+    "eval": "in this server's own Python process",
+    "jupyter-server": "in a Jupyter kernel the server starts beside itself",
+    "docker": "in a container",
+    "datalayer": "on a Datalayer runtime in the cloud",
+    "google-colab": "on a Google Colab runtime",
+    "kaggle": "on a Kaggle kernel",
+    "monty": "in the Monty interpreter, a restricted in-process sandbox",
+    "modal": "on a Modal cloud sandbox",
+}
 
 
 def _content_for_variant(variant: str) -> str:
-    variant_title = variant.capitalize()
-    spec_id = f"example-sandbox-{variant}"
-    emoji = _emoji_for_variant(variant)
-
+    key = VARIANTS[variant]
+    title = _TITLES[variant]
+    where = _WHERE[variant]
+    spec_id = f"example-sandbox-{key}"
     return f"""# Copyright (c) 2025-2026 Datalayer, Inc.
 # Distributed under the terms of the Modified BSD License.
 
 # Agent Specification: Sandbox Variant ({variant})
+# Scaffolded by scripts/codegen/generate_sandbox_agents.py — edit the template
+# there, not this file. Used by AgentCodeSandboxesExample.
 
 id: {spec_id}
 version: 0.0.1
-name: Example Sandbox {variant_title} Agent
+name: Example Sandbox {title} Agent
 description: >-
-  Demonstration agent configured to run codemode code execution with the
-  '{variant}' sandbox variant.
+  Demonstrates the '{variant}' code sandbox: Python the agent runs through
+  execute_code executes {where}.
 
 tags:
   - sandbox
-  - codemode
-  - {variant}
+  - code-execution
+  - {key}
 
 enabled: true
-model: "bedrock:us.anthropic.claude-opus-4-8"
+model: "bedrock:us.anthropic.claude-sonnet-4-6"
+harness: pydantic-ai
 
 sandbox_variant: {variant}
 memory: ephemeral
 
-mcp_servers:
-  - tavily:0.0.1
+mcp_servers: []
 
-skills:
-  - events:0.0.1
+skills: []
 
-tools:
-  - runtime-echo:0.0.1
+tools: []
 
-frontend_tools:
-  - jupyter-notebook:0.0.1
-  - lexical-document:0.0.1
+frontend_tools: []
 
 environment_name: ai-agents-env
 
 icon: package
-emoji: "{emoji}"
+emoji: "📦"
 color: "#1F6FEB"
 
 suggestions:
-  - "Use execute_code to print('sandbox variant: {variant}')"
-  - "Use execute_code to compute sum(i*i for i in range(20))"
-  - "Use execute_code to load pandas and build a small DataFrame"
+  # First: proof of where the code runs — the point of a variant.
+  - text: >-
+      Run Python that prints platform.platform(), sys.version and
+      os.getenv("DATALAYER_CODE_SANDBOX_VARIANT"), and tell me where this
+      code ran.
+    summary: "Where does my code run?"
+  - text: "Run Python that prints sum(i*i for i in range(20))."
+    summary: "Sum of squares"
+  - text: >-
+      Run Python that builds a small pandas DataFrame of three cities and
+      their populations and prints it sorted by population.
+    summary: "Small DataFrame"
 
 welcome_message: >-
-  You're connected to the {variant} sandbox variant demo. Ask me to run
-  Python code and I will use execute_code in codemode.
+  You're connected to the {variant} sandbox. Ask me to run Python: it
+  executes {where}.
 
 system_prompt: >-
-  You are a sandbox-variant demonstration assistant. Prefer executing
-  Python code via execute_code for computations, data checks, and quick
-  experiments, then summarize results clearly.
-
-system_prompt_codemode_addons: >-
-  Always use execute_code when the user requests calculations, scripts,
-  DataFrame operations, package checks, or shell-style diagnostics.
+  You are the {title} sandbox example agent. Any computation, script or
+  check the person asks for is done by running Python in the sandbox with
+  `execute_code` — never by working it out yourself. Run the code, report
+  what it printed, briefly, and when asked where the code ran, answer from
+  what the code printed. Answer in the conversation, and only with the
+  tools you actually have; never call a tool you were not given.
 
-codemode:
-  enabled: true
-  token_reduction: "~80%"
-  speedup: "~1.5x"
+system_prompt_codemode_addons: null
 
 welcome_notebook: null
 welcome_document: null
+
 trigger: null
 """
 
@@ -118,8 +132,8 @@ trigger: null
 def generate_specs(agents_dir: Path) -> int:
     agents_dir.mkdir(parents=True, exist_ok=True)
     count = 0
-    for variant in VARIANTS:
-        path = agents_dir / f"example-sandbox-{variant}.yaml"
+    for variant, key in VARIANTS.items():
+        path = agents_dir / f"example-sandbox-{key}.yaml"
         path.write_text(_content_for_variant(variant), encoding="utf-8")
         count += 1
     return count

package/scripts/codegen/generate_teams.py

@@ -22,6 +22,23 @@ import yaml
 from versioning import ensure_spec_version, version_suffix
 
 
+def _suggestion_fields(item: Any) -> Dict[str, Any]:
+    """A suggestion's fields, from either shape it may be written in.
+
+    A bare string is still read as a suggestion with no marks — see the same
+    helper in `generate_agents.py`.
+    """
+    if isinstance(item, str):
+        return {"text": item}
+    return {
+        "text": item.get("text", ""),
+        # The label, when the text is too long to be one.
+        "summary": item.get("summary"),
+        "icon": item.get("icon"),
+        "emoji": item.get("emoji"),
+    }
+
+
 def _make_const_name(team_id: str) -> str:
     """Convert a team ID to a constant name (e.g., 'analyze-campaign-performance' -> 'ANALYZE_CAMPAIGN_PERFORMANCE_TEAM_SPEC')."""
     return f"{team_id.upper().replace('-', '_')}_TEAM_SPEC"
@@ -103,15 +120,47 @@ def load_yaml_specs(specs_dir: Path) -> List[tuple[str, Dict[str, Any]]]:
     return specs
 
 
+def _generate_team_subagent_py(subagent: Dict[str, Any]) -> str:
+    """Generate Python code for a TeamSubagentspec."""
+    description = (
+        subagent.get("description", "").replace('"', '\\"').replace("\n", " ").strip()
+    )
+    instructions = (
+        subagent.get("instructions", "").replace('"', '\\"').replace("\n", " ").strip()
+    )
+    return (
+        "TeamSubagentspec("
+        f'name="{subagent.get("name", "")}", '
+        f'ref="{subagent.get("ref", "")}", '
+        f'description="{description}", '
+        f'instructions="{instructions}"'
+        ")"
+    )
+
+
 def _generate_team_agent_py(agent: Dict[str, Any]) -> str:
     """Generate Python code for a TeamAgentspec."""
     lines = []
     lines.append("TeamAgentspec(")
     lines.append(f'            id="{agent.get("id", "")}",')
     lines.append(f'            name="{agent.get("name", "")}",')
-    lines.append(f'            role="{agent.get("role", "")}",')
+    # The reference into the agent catalogue. Emitted before the overrides
+    # because it is what the member *is*; the rest says how it differs here.
+    lines.append(f'            ref="{agent.get("ref", "")}",')
+    lines.append(f'            role="{agent.get("role", "contributor")}",')
     goal = agent.get("goal", "").replace('"', '\\"').replace("\n", " ").strip()
     lines.append(f'            goal="{goal}",')
+    lines.append(f"            depends_on={_fmt_list(agent.get('depends_on', []))},")
+    subagents = agent.get("subagents", [])
+    if subagents:
+        rendered = ",\n                ".join(
+            _generate_team_subagent_py(sub) for sub in subagents
+        )
+        lines.append(
+            f"            subagents=[\n                {rendered},\n            ],"
+        )
+    else:
+        lines.append("            subagents=[],")
     lines.append(f'            model="{agent.get("model", "")}",')
     lines.append(f'            mcp_server="{agent.get("mcp_server", "")}",')
     tools = agent.get("tools", [])
@@ -123,16 +172,46 @@ def _generate_team_agent_py(agent: Dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
+def _generate_team_subagent_ts(subagent: Dict[str, Any]) -> str:
+    """Generate TypeScript code for a TeamSubagentspec."""
+    description = (
+        subagent.get("description", "").replace("`", "\\`").replace("\n", " ").strip()
+    )
+    instructions = (
+        subagent.get("instructions", "").replace("`", "\\`").replace("\n", " ").strip()
+    )
+    return (
+        "{ "
+        f"name: '{subagent.get('name', '')}', "
+        f"ref: '{subagent.get('ref', '')}', "
+        f"description: `{description}`, "
+        f"instructions: `{instructions}`"
+        " }"
+    )
+
+
 def _generate_team_agent_ts(agent: Dict[str, Any]) -> str:
     """Generate TypeScript code for a TeamAgentspec."""
     goal = agent.get("goal", "").replace("`", "\\`").replace("\n", " ").strip()
     tools = json.dumps(agent.get("tools", []))
+    depends_on = json.dumps(agent.get("depends_on", []))
     trigger = agent.get("trigger", "").replace("'", "\\'")
+    subagents = agent.get("subagents", [])
+    rendered = (
+        "[\n        "
+        + ",\n        ".join(_generate_team_subagent_ts(sub) for sub in subagents)
+        + ",\n      ]"
+        if subagents
+        else "[]"
+    )
     return f"""    {{
       id: '{agent.get("id", "")}',
       name: '{agent.get("name", "")}',
-      role: '{agent.get("role", "")}',
+      ref: '{agent.get("ref", "")}',
+      role: '{agent.get("role", "contributor")}',
       goal: `{goal}`,
+      dependsOn: {depends_on},
+      subagents: {rendered},
       model: '{agent.get("model", "")}',
       mcpServer: '{agent.get("mcp_server", "")}',
       tools: {tools},
@@ -157,10 +236,14 @@ from typing import Dict, Optional
 
 from agent_runtimes.types import (
     TeamAgentspec,
+    TeamContextSpec,
+    TeamDelegationSpec,
+    TeamSubagentspec,
     TeamHealthMonitoring,
     TeamOutputSpec,
     TeamReactionRule,
     TeamSpec,
+    TeamSuggestionSpec,
     TeamSupervisorSpec,
     TeamValidationSpec,
 )
@@ -218,8 +301,25 @@ from agent_runtimes.types import (
             if supervisor and isinstance(supervisor, dict):
                 sup_name = supervisor.get("name", "").replace('"', '\\"')
                 sup_model = supervisor.get("model", "")
+                sup_ref = supervisor.get("ref", "")
+                sup_goal = (
+                    supervisor.get("goal", "")
+                    .replace('"', '\\"')
+                    .replace("\n", " ")
+                    .strip()
+                )
+                sup_instructions = (
+                    supervisor.get("instructions", "")
+                    .replace('"', '\\"')
+                    .replace("\n", " ")
+                    .strip()
+                )
                 supervisor_code = (
-                    f'TeamSupervisorSpec(name="{sup_name}", model="{sup_model}")'
+                    f'TeamSupervisorSpec(name="{sup_name}", ref="{sup_ref}", '
+                    f'model="{sup_model}", goal="{sup_goal}", '
+                    f'instructions="{sup_instructions}", '
+                    f'approval="{supervisor.get("approval", "auto")}", '
+                    f"can_terminate={bool(supervisor.get('can_terminate', True))})"
                 )
             else:
                 supervisor_code = "None"
@@ -326,6 +426,35 @@ from agent_runtimes.types import (
             )
             code += f"    supervisor={supervisor_code},\n"
             code += f'    routing_instructions="{routing}",\n'
+            suggestions = spec.get("suggestions") or []
+            if suggestions:
+                rendered = ", ".join(
+                    "TeamSuggestionSpec("
+                    + ", ".join(
+                        f"{key}={value!r}"
+                        for key, value in _suggestion_fields(item).items()
+                        if value
+                    )
+                    + ")"
+                    for item in suggestions
+                )
+                code += f"    suggestions=[{rendered}],\n"
+            delegation = spec.get("delegation") or {}
+            code += (
+                "    delegation=TeamDelegationSpec("
+                f"max_depth={delegation.get('max_depth', 2)}, "
+                f"allow_peer_delegation={bool(delegation.get('allow_peer_delegation', False))}, "
+                f"include_general_purpose={bool(delegation.get('include_general_purpose', False))}"
+                "),\n"
+            )
+            # `shared` by default: routing only makes sense if the member
+            # receiving the work can see what was already said.
+            context = spec.get("context") or {}
+            code += (
+                "    context=TeamContextSpec("
+                f'sharing="{context.get("sharing", "shared")}"'
+                "),\n"
+            )
             code += f"    validation={validation_code},\n"
             code += f"    agents={agents_code},\n"
             if reaction_rules_code != "None":
@@ -454,7 +583,26 @@ import type {{ TeamSpec }} from '{types_import_path}';
             if supervisor and isinstance(supervisor, dict):
                 sup_name = supervisor.get("name", "").replace("'", "\\'")
                 sup_model = supervisor.get("model", "")
-                supervisor_ts = f"{{ name: '{sup_name}', model: '{sup_model}' }}"
+                sup_ref = supervisor.get("ref", "")
+                sup_goal = (
+                    supervisor.get("goal", "")
+                    .replace("`", "\\`")
+                    .replace("\n", " ")
+                    .strip()
+                )
+                sup_instructions = (
+                    supervisor.get("instructions", "")
+                    .replace("`", "\\`")
+                    .replace("\n", " ")
+                    .strip()
+                )
+                supervisor_ts = (
+                    f"{{ name: '{sup_name}', ref: '{sup_ref}', "
+                    f"model: '{sup_model}', goal: `{sup_goal}`, "
+                    f"instructions: `{sup_instructions}`, "
+                    f"approval: '{supervisor.get('approval', 'auto')}', "
+                    f"canTerminate: {str(bool(supervisor.get('can_terminate', True))).lower()} }}"
+                )
             else:
                 supervisor_ts = "undefined"
 
@@ -566,6 +714,32 @@ import type {{ TeamSpec }} from '{types_import_path}';
             code += f"  executionMode: '{spec.get('execution_mode', 'sequential')}',\n"
             code += f"  supervisor: {supervisor_ts},\n"
             code += f"  routingInstructions: `{routing}`,\n"
+            # What an empty chat offers. Emitted only when the team names
+            # some: an empty array in every generated team would be four
+            # hundred lines saying nothing.
+            suggestions = spec.get("suggestions") or []
+            if suggestions:
+                rendered = ", ".join(
+                    "{ "
+                    + ", ".join(
+                        f"{key}: " + json.dumps(value, ensure_ascii=False)
+                        for key, value in _suggestion_fields(item).items()
+                        if value
+                    )
+                    + " }"
+                    for item in suggestions
+                )
+                code += f"  suggestions: [{rendered}],\n"
+            delegation = spec.get("delegation") or {}
+            code += (
+                "  delegation: { "
+                f"maxDepth: {delegation.get('max_depth', 2)}, "
+                f"allowPeerDelegation: {str(bool(delegation.get('allow_peer_delegation', False))).lower()}, "
+                f"includeGeneralPurpose: {str(bool(delegation.get('include_general_purpose', False))).lower()}"
+                " },\n"
+            )
+            context = spec.get("context") or {}
+            code += f"  context: {{ sharing: '{context.get('sharing', 'shared')}' }},\n"
             code += f"  validation: {validation_ts},\n"
             code += f"  agents: {agents_ts},\n"
             if rr_ts is not None:

package/scripts/codegen/generate_tools.py

@@ -7,6 +7,7 @@ Generate Python and TypeScript code from YAML tool specifications.
 """
 
 import argparse
+import json
 import re
 import sys
 from pathlib import Path
@@ -123,8 +124,8 @@ def generate_python_code(specs: list[dict[str, Any]]) -> str:
                 f"{const_name} = ToolSpec(",
                 f'    id="{tool_id}",',
                 f'    version="{version}",',
-                f'    name="{spec["name"]}",',
-                f'    description="{spec.get("description", "")}",',
+                f"    name={json.dumps(spec['name'], ensure_ascii=False)},",
+                f"    description={json.dumps(spec.get('description', ''), ensure_ascii=False)},",
                 f"    tags={_fmt_list(spec.get('tags', []))},",
                 f"    enabled={spec.get('enabled', True)},",
                 f'    approval="{spec.get("approval", "auto")}",',
@@ -229,8 +230,9 @@ def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
                 f"export const {const_name}: ToolSpec = {{",
                 f"  id: '{tool_id}',",
                 f"  version: '{version}',",
-                f"  name: '{spec['name']}',",
-                f"  description: '{spec.get('description', '')}',",
+                # JSON-escaped: an apostrophe in a description is not a syntax error.
+                f"  name: {json.dumps(spec['name'], ensure_ascii=False)},",
+                f"  description: {json.dumps(spec.get('description', ''), ensure_ascii=False)},",
                 f"  tags: {tags_json},",
                 f"  enabled: {str(spec.get('enabled', True)).lower()},",
                 f"  approval: '{spec.get('approval', 'auto')}',",