commands.agents

Agent runtime commands for Datalayer CLI.

agents_callback

@app.callback()
def agents_callback(ctx: typer.Context) -> None

Agent runtime management commands.

list_agents

@app.command(name="ls")
def list_agents(token: Optional[str] = typer.Option(
    None,
    "--api-key",
    help="API key (Bearer token for API requests).",
),
                iam_url: Optional[str] = typer.Option(
                    None,
                    "--iam-url",
                    help="Datalayer IAM server URL",
                ),
                runtimes_url: Optional[str] = typer.Option(
                    None,
                    "--runtimes-url",
                    help="Datalayer Runtimes server URL",
                )) -> None

List running agent runtimes.

create_agent_runtime

@app.command(name="create")
def create_agent_runtime(
        environment: Optional[str] = typer.Argument(None,
                                                    help="Environment name."),
        given_name: Optional[str] = typer.Option(
            None,
            "--given-name",
            help="Custom name for the runtime.",
        ),
        spec_id: Optional[str] = typer.
    Option(
        None,
        "--agentspec-id",
        help=(
            "Agentspec id for runtime bootstrap. "
            f"Defaults to {DEFAULT_AGENT_SPEC_ID} when --agentspec is omitted."
        ),
    ),
        spec: Optional[str] = typer.Option(
            None,
            "--agentspec",
            help="Agentspec source as YAML/JSON URL or local file path.",
        ),
        time_reservation: Optional[float] = typer.Option(
            10.0,
            "--time-reservation",
            help="Time reservation in minutes for the runtime.",
        ),
        billing_entity_uid: Optional[str] = typer.Option(
            None,
            "--billing-entity-uid",
            help="Account UID to bill the runtime to (org/team).",
        ),
        billing_entity_type: Optional[str] = typer.Option(
            None,
            "--billing-entity-type",
            help="Billing Entity type: user, organization, or team.",
        ),
        billing_entity_handle: Optional[str] = typer.Option(
            None,
            "--billing-entity-handle",
            help="Billing Entity handle (informational).",
        ),
        raw: bool = typer.Option(
            False,
            "--raw",
            help="Print machine-readable JSON payload.",
        ),
        token: Optional[str] = typer.Option(
            None,
            "--api-key",
            help="API key (Bearer token for API requests).",
        ),
        iam_url: Optional[str] = typer.Option(
            None,
            "--iam-url",
            help="Datalayer IAM server URL",
        ),
        runtimes_url: Optional[str] = typer.Option(
            None,
            "--runtimes-url",
            help="Datalayer Runtimes server URL",
        ),
        local: bool = typer.Option(
            False,
            "--local",
            help="Launch the agent as a local agent-runtimes server.",
        ),
        cloud: bool = typer.Option(
            False,
            "--cloud",
            help="Launch the agent as a cloud runtime.",
        ),
        host: str = typer.Option(
            DEFAULT_LOCAL_HOST,
            "--host",
            help="Host interface for the local runtime (only with --local).",
        ),
        port: Optional[int] = typer.
    Option(
        None,
        "--port",
        help=
        "Port for the local runtime (random free port when omitted, only with --local).",
    ),
        protocol: str = typer.
    Option(
        DEFAULT_LOCAL_PROTOCOL,
        "--protocol",
        help="Transport protocol for the local runtime (only with --local).",
    ),
        log_level: str = typer.
    Option(
        DEFAULT_LOCAL_LOG_LEVEL,
        "--log-level",
        help="Log level for the local runtime process (only with --local).",
    )) -> None

Create a new runtime preloaded with an agentspec.

By default creates a cloud runtime. Use --local for a local agent-runtimes server, or --cloud to be explicit.

get_agent_runtime

@app.command(name="get")
def get_agent_runtime(pod_name: Optional[str] = typer.Argument(
    None,
    help="Pod name of the agent runtime to read.",
),
                      raw: bool = typer.Option(
                          False,
                          "--raw",
                          help="Print machine-readable JSON payload.",
                      ),
                      token: Optional[str] = typer.Option(
                          None,
                          "--api-key",
                          help="API key (Bearer token for API requests).",
                      ),
                      iam_url: Optional[str] = typer.Option(
                          None,
                          "--iam-url",
                          help="Datalayer IAM server URL",
                      ),
                      runtimes_url: Optional[str] = typer.Option(
                          None,
                          "--runtimes-url",
                          help="Datalayer Runtimes server URL",
                      )) -> None

Read a single agent runtime by pod name.

update_agent_runtime

@app.command(name="update")
def update_agent_runtime(
        pod_name: Optional[str] = typer.Argument(
            None,
            help="Pod name of the agent runtime to update.",
        ),
        capability: list[str] = typer.
    Option(
        [],
        "--capability",
        help=
        "Capability to apply (repeatable). Replaces existing capabilities.",
    ),
        raw: bool = typer.Option(
            False,
            "--raw",
            help="Print machine-readable JSON payload.",
        ),
        token: Optional[str] = typer.Option(
            None,
            "--api-key",
            help="API key (Bearer token for API requests).",
        ),
        iam_url: Optional[str] = typer.Option(
            None,
            "--iam-url",
            help="Datalayer IAM server URL",
        ),
        runtimes_url: Optional[str] = typer.Option(
            None,
            "--runtimes-url",
            help="Datalayer Runtimes server URL",
        )) -> None

Update an agent runtime's capabilities.

terminate_agent_runtime

@app.command(name="delete")
@app.command(name="terminate")
def terminate_agent_runtime(
        pod_name: Optional[str] = typer.Argument(
            None,
            help="Pod name of the runtime to terminate.",
        ),
        token: Optional[str] = typer.Option(
            None,
            "--api-key",
            help="API key (Bearer token for API requests).",
        ),
        iam_url: Optional[str] = typer.Option(
            None,
            "--iam-url",
            help="Datalayer IAM server URL",
        ),
        runtimes_url: Optional[str] = typer.Option(
            None,
            "--runtimes-url",
            help="Datalayer Runtimes server URL",
        )) -> None

Terminate a running agent runtime.

agents_ls

def agents_ls(token: Optional[str] = typer.Option(
    None,
    "--api-key",
    help="API key (Bearer token for API requests).",
),
              iam_url: Optional[str] = typer.Option(
                  None,
                  "--iam-url",
                  help="Datalayer IAM server URL",
              ),
              runtimes_url: Optional[str] = typer.Option(
                  None,
                  "--runtimes-url",
                  help="Datalayer Runtimes server URL",
              )) -> None

List running agent runtimes (root command alias).

inspect_agent_runtime

@app.command(name="inspect")
def inspect_agent_runtime(agent: Optional[str] = typer.Option(
    None,
    "--agent",
    "-a",
    help=
    "Agent identifier (pod name, uid, or given name). Defaults to first running runtime.",
),
                          token: Optional[str] = typer.Option(
                              None,
                              "--api-key",
                              help="API key (Bearer token for API requests).",
                          ),
                          iam_url: Optional[str] = typer.Option(
                              None,
                              "--iam-url",
                              help="Datalayer IAM server URL",
                          ),
                          runtimes_url: Optional[str] = typer.Option(
                              None,
                              "--runtimes-url",
                              help="Datalayer Runtimes server URL",
                          )) -> None

Inspect an agent runtime and list available code sandboxes.

health_agent_runtime

@app.command(name="health")
def health_agent_runtime(agent: Optional[str] = typer.Option(
    None,
    "--agent",
    "-a",
    help=
    "Agent identifier (pod name, uid, or given name). Defaults to first running runtime.",
),
                         token: Optional[str] = typer.Option(
                             None,
                             "--api-key",
                             help="API key (Bearer token for API requests).",
                         ),
                         iam_url: Optional[str] = typer.Option(
                             None,
                             "--iam-url",
                             help="Datalayer IAM server URL",
                         ),
                         runtimes_url: Optional[str] = typer.Option(
                             None,
                             "--runtimes-url",
                             help="Datalayer Runtimes server URL",
                         )) -> None

Check agent runtime health by executing a probe on the sandbox.