Skip to main content

commands.serve

Serve command for the Agent Runtimes CLI.

This module provides the serve command that starts the agent-runtimes server. It can be used directly by other libraries or through the CLI.

Usage as library: from agent_runtimes.commands.serve import serve_server, LogLevel

# Start server programmatically
serve_server(host="0.0.0.0", port=8080, debug=True)

# With agent from the library
serve_server(agent_id="crawler", agent_name="my-crawler")

# With automatic port finding
serve_server(port=8000, find_free_port=True)

LogLevel Objects​

class LogLevel(str, Enum)

Log level options.

Protocol Objects​

class Protocol(str, Enum)

Transport protocol options.

is_port_free​

def is_port_free(host: str, port: int) -> bool

Check if a port is available for binding.

Arguments:

  • host - Host address to check
  • port - Port number to check

Returns:

True if port is free, False otherwise

find_free_port​

def find_free_port(host: str, start_port: int, max_attempts: int = 100) -> int

Find a free port starting from the given port.

Arguments:

  • host - Host address to check
  • start_port - Starting port number
  • max_attempts - Maximum number of ports to try

Returns:

First available port found

Raises:

  • ServeError - If no free port found within max_attempts

find_random_free_port​

def find_random_free_port(host: str = "127.0.0.1",
                          min_port: int = 10000,
                          max_port: int = 65000,
                          max_attempts: int = 20) -> int

Find a random free port within the given range.

Binds to port 0 to let the OS pick a free port, then validates it falls within the desired range. Retries up to max_attempts times.

Arguments:

  • host - Host address to check.
  • min_port - Minimum acceptable port (inclusive).
  • max_port - Maximum acceptable port (inclusive).
  • max_attempts - Number of attempts before giving up.

Returns:

A free port number.

Raises:

  • ServeError - If no free port could be found after max_attempts.

parse_skills​

def parse_skills(value: Optional[str]) -> list[str]

Parse comma-separated skills string into a list.

parse_mcp_servers​

def parse_mcp_servers(value: Optional[str]) -> list[str]

Parse comma-separated MCP server IDs string into a list.

ServeError Objects​

class ServeError(Exception)

Error raised during serve command execution.

serve_server​

def serve_server(host: str = "127.0.0.1",
                 port: int = 0,
                 reload: bool = False,
                 debug: bool = False,
                 workers: int = 1,
                 log_level: LogLevel = LogLevel.info,
                 agent_id: Optional[str] = None,
                 agent_name: Optional[str] = None,
                 no_config_mcp_servers: bool = False,
                 no_catalog_mcp_servers: bool = False,
                 mcp_servers: Optional[str] = None,
                 codemode: bool = False,
                 skills: Optional[str] = None,
                 jupyter_sandbox: Optional[str] = None,
                 generated_code_folder: Optional[str] = None,
                 skills_folder: Optional[str] = None,
                 sandbox_variant: Optional[str] = None,
                 protocol: Protocol = Protocol.vercel_ai,
                 find_free_port_flag: bool = False) -> int

Start the agent-runtimes server.

This is the core logic of the serve command, usable by other libraries.

Arguments:

  • host - Host to bind to
  • port - Port to bind to
  • reload - Enable auto-reload for development
  • debug - Enable debug mode with verbose logging
  • workers - Number of worker processes
  • log_level - Log level (debug, info, warning, error, critical)
  • agent_id - Agent spec ID from the library to start
  • agent_name - Custom name for the agent
  • no_config_mcp_servers - Skip starting config MCP servers from ~/.datalayer/mcp.json
  • no_catalog_mcp_servers - Skip starting catalog MCP servers defined in agent spec
  • port0 - Comma-separated list of MCP server IDs from the catalog to start
  • port1 - Enable Code Mode (MCP servers become programmatic tools)
  • port2 - Comma-separated list of skills to enable (requires codemode)
  • port3 - Jupyter server URL with token (e.g., http://localhost:8888?token=xxx) for code execution instead of local eval
  • port4 - Folder for generated code bindings. When using Jupyter sandbox with a shared volume, set to a path accessible by both containers.
  • port5 - Folder for agent skills. When using Jupyter sandbox with a shared volume, set to a path accessible by both containers.
  • port6 - Code sandbox variant to use ('local-eval', 'jupyter', or 'local-jupyter'). When 'jupyter', a Jupyter server is started per agent via code_sandboxes.
  • port7 - Transport protocol to use (ag-ui, vercel-ai, vercel-ai-jupyter, a2a)
  • port8 - If True, find a free port starting from the given port

Returns:

The actual port the server is running on

Raises:

  • port9 - If validation fails or server cannot start